@flowy-agent-store/client 0.1.0-beta.3 → 0.1.0-beta.5

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.cjs CHANGED
@@ -238,6 +238,535 @@ var WebSocketTransport = class {
238
238
  }
239
239
  };
240
240
  //#endregion
241
+ //#region src/http-transport.ts
242
+ /**
243
+ * HTTP transport binding (doc `16` R2 / `05` §2.1.1).
244
+ *
245
+ * ## What this is
246
+ *
247
+ * The App Server exposes one method semantics over two bindings. This class is
248
+ * the **request/response** binding: it maps a protocol method name onto the
249
+ * server's hand-written REST route and returns the same result body the
250
+ * WebSocket binding would.
251
+ *
252
+ * ## What this is not
253
+ *
254
+ * - **No server push.** HTTP has no notification channel, so `onNotification`
255
+ * hands back a no-op unsubscribe and `notify` throws. Live conversation / run
256
+ * events and subscription methods (`conversation/subscribe`, `run/subscribe`)
257
+ * exist **only** over `WebSocketTransport`; an `HttpTransport` is not a
258
+ * drop-in replacement for it. Consumers that need events must connect over
259
+ * WS (or run both).
260
+ * - **One-shot handshake per call.** `05` §2.1.1: *each* HTTP call performs its
261
+ * own `POST /initialize` → `POST /initialized` → business call, after which
262
+ * the connection id expires. `connect()` therefore has nothing to hold open
263
+ * and is a no-op; it does not warm anything up.
264
+ * - **Host file services stay out.** `/api/fs/*` (browse / list / read /
265
+ * metadata) is a host file service on the server *root*, explicitly not a
266
+ * protocol method (`05` §2.1.1), so it is not reachable through this class.
267
+ *
268
+ * ## The route table
269
+ *
270
+ * Every entry was read out of the handler bodies in
271
+ * `crates/backend/nomifun-app-server/src/lib.rs` — the `source` field records
272
+ * which handler (and, where one exists, which shared `*_impl`) proves the two
273
+ * bindings run the same operation. Methods with no entry throw
274
+ * `TransportError("send", …)` instead of silently degrading.
275
+ */
276
+ /** Header the server mints the per-call connection id under. */
277
+ const CONNECTION_HEADER = "x-app-server-connection-id";
278
+ /** Protocol version this binding announces on the one-shot handshake. */
279
+ const PROTOCOL_VERSION = "fp-7";
280
+ /**
281
+ * Protocol method → REST route. Verified from handler bodies, not from the
282
+ * route list (a route existing does not prove which method it mirrors).
283
+ */
284
+ const HTTP_ROUTES = {
285
+ ping: {
286
+ verb: "POST",
287
+ path: "/ping",
288
+ source: "ping() -> registry.require_ready"
289
+ },
290
+ "workspace/list": {
291
+ verb: "GET",
292
+ path: "/workspaces",
293
+ source: "workspace_list() -> owner-scoped active rows"
294
+ },
295
+ "workspace/revoke": {
296
+ verb: "DELETE",
297
+ path: "/workspaces/:workspace_id",
298
+ source: "workspace_delete() -> workspace_revoke_impl (shared with the WS arm)"
299
+ },
300
+ "conversation/create": {
301
+ verb: "POST",
302
+ path: "/conversations",
303
+ source: "conversation_create() -> create_conversation_for_user (shared)"
304
+ },
305
+ "conversation/list": {
306
+ verb: "GET",
307
+ path: "/conversations",
308
+ query: ["limit"],
309
+ source: "conversation_list() -> list_app_server_chats (shared); Query<limit>"
310
+ },
311
+ "conversation/get": {
312
+ verb: "GET",
313
+ path: "/conversations/:conversation_id",
314
+ source: "conversation_get() -> project_conversation_view (shared)"
315
+ },
316
+ "conversation/delete": {
317
+ verb: "DELETE",
318
+ path: "/conversations/:conversation_id",
319
+ source: "conversation_delete() -> conversation/delete arm semantics"
320
+ },
321
+ "conversation/messages": {
322
+ verb: "GET",
323
+ path: "/conversations/:conversation_id/messages",
324
+ query: [
325
+ "page",
326
+ "page_size",
327
+ "cursor"
328
+ ],
329
+ source: "conversation_messages() -> list_conversation_messages_for_user (shared)"
330
+ },
331
+ "conversation/send": {
332
+ verb: "POST",
333
+ path: "/conversations/:conversation_id/messages",
334
+ body: [
335
+ "content",
336
+ "idempotency_key",
337
+ "attachments",
338
+ "mentions",
339
+ "model",
340
+ "reasoning_effort"
341
+ ],
342
+ source: "conversation_send() -> send_conversation_message_for_user (shared with the WS arm)"
343
+ },
344
+ "conversation/cancel": {
345
+ verb: "POST",
346
+ path: "/conversations/:conversation_id/cancel",
347
+ source: "conversation_cancel() -> cancel arm semantics"
348
+ },
349
+ "agent/run": {
350
+ verb: "POST",
351
+ path: "/agent/run",
352
+ source: "agent_run() -> same request/receipt as the `agent/run` arm"
353
+ },
354
+ "team/run": {
355
+ verb: "POST",
356
+ path: "/team/run",
357
+ source: "team_run() -> execute_team_run() (same as the WS arm); Leader Conversation + planned delegation, `TeamRunReceipt`"
358
+ },
359
+ "run/get": {
360
+ verb: "GET",
361
+ path: "/run/:run_id",
362
+ source: "run_get()"
363
+ },
364
+ "run/result": {
365
+ verb: "GET",
366
+ path: "/run/:run_id/result",
367
+ source: "run_result()"
368
+ },
369
+ "run/plan": {
370
+ verb: "GET",
371
+ path: "/run/:run_id/plan",
372
+ source: "run_plan() -> get_run_plan_for_user() (same as the WS arm)"
373
+ },
374
+ "run/events": {
375
+ verb: "GET",
376
+ path: "/run/:run_id/events",
377
+ query: ["after_sequence", "limit"],
378
+ source: "run_events() -> runtime.list_events(after_sequence, limit) (same as the WS arm)"
379
+ },
380
+ "run/cancel": {
381
+ verb: "POST",
382
+ path: "/run/:run_id/cancel",
383
+ body: [
384
+ "expected_version",
385
+ "reason",
386
+ "idempotency_key"
387
+ ],
388
+ source: "run_cancel() -> same CancelRunRequest as the WS arm"
389
+ },
390
+ "run/steer": {
391
+ verb: "POST",
392
+ path: "/run/:run_id/steer",
393
+ body: [
394
+ "text",
395
+ "expected_version",
396
+ "command_id",
397
+ "idempotency_key"
398
+ ],
399
+ source: "run_steer() -> execute_steer_run (shared with the WS arm)"
400
+ },
401
+ "run/answer-decision": {
402
+ verb: "POST",
403
+ path: "/run/:run_id/answer-decision",
404
+ body: [
405
+ "step_id",
406
+ "attempt_id",
407
+ "answer",
408
+ "expected_execution_version",
409
+ "expected_step_version",
410
+ "expected_attempt_version"
411
+ ],
412
+ source: "run_answer_decision() -> execute_answer_decision (shared with the WS arm; engine answer gate, no always_allow)"
413
+ },
414
+ "skill/list": {
415
+ verb: "GET",
416
+ path: "/skills",
417
+ source: "list_skills_route() -> list_skills_impl"
418
+ },
419
+ "skill/get": {
420
+ verb: "GET",
421
+ path: "/skills/:skill_id",
422
+ source: "get_skill_route() -> get_skill_impl"
423
+ },
424
+ "skill/files": {
425
+ verb: "GET",
426
+ path: "/skills/:skill_id/files",
427
+ source: "list_skill_files_route() -> list_skill_files_impl"
428
+ },
429
+ "connector/list": {
430
+ verb: "GET",
431
+ path: "/connectors",
432
+ source: "list_connectors_route() -> list_connectors_impl"
433
+ },
434
+ "models/list": {
435
+ verb: "GET",
436
+ path: "/models",
437
+ source: "list_models_route() -> list_models_impl"
438
+ },
439
+ "connector/get": {
440
+ verb: "GET",
441
+ path: "/connectors/:connector_id",
442
+ source: "get_connector_route() -> get_connector_impl"
443
+ },
444
+ "connector/status": {
445
+ verb: "GET",
446
+ path: "/connectors/:connector_id/status",
447
+ source: "connector_status_route() -> connector_status_impl"
448
+ },
449
+ "connector/test": {
450
+ verb: "POST",
451
+ path: "/connectors/:connector_id/test",
452
+ source: "connector_test_route() -> connector_test_impl"
453
+ },
454
+ "connector/call": {
455
+ verb: "POST",
456
+ path: "/connectors/:connector_id/call",
457
+ source: "connector_call_route() -> connector_call_impl"
458
+ },
459
+ "connector/auth/start": {
460
+ verb: "POST",
461
+ path: "/connectors/:connector_id/auth-start",
462
+ source: "connector_auth_start_route() -> connector_auth_start_impl (WS name uses slashes)"
463
+ },
464
+ "connector/auth/status": {
465
+ verb: "GET",
466
+ path: "/connectors/:connector_id/auth-status",
467
+ source: "connector_auth_status_route() -> connector_auth_status_impl"
468
+ },
469
+ "connector/auth/logout": {
470
+ verb: "POST",
471
+ path: "/connectors/:connector_id/auth-logout",
472
+ source: "connector_auth_logout_route() -> connector_auth_logout_impl"
473
+ },
474
+ "import/run": {
475
+ verb: "POST",
476
+ path: "/imports",
477
+ source: "run_import_route() -> run_import_impl"
478
+ },
479
+ "import/list": {
480
+ verb: "GET",
481
+ path: "/imports",
482
+ source: "list_imports_route() -> list_imports_impl"
483
+ },
484
+ "import/get": {
485
+ verb: "GET",
486
+ path: "/imports/:snapshot_id",
487
+ source: "get_import_route() -> get_import_impl"
488
+ },
489
+ "install/run": {
490
+ verb: "POST",
491
+ path: "/installs",
492
+ source: "run_install_route() -> install_impl"
493
+ },
494
+ "install/status": {
495
+ verb: "GET",
496
+ path: "/installs/:snapshot_id",
497
+ source: "install_status_route() -> install_status_impl"
498
+ },
499
+ "install/disable": {
500
+ verb: "POST",
501
+ path: "/installs/:snapshot_id/disable",
502
+ body: ["component_ids"],
503
+ source: "install_disable_route() -> install_disable_impl; body `component_ids`"
504
+ },
505
+ "install/enable": {
506
+ verb: "POST",
507
+ path: "/installs/:snapshot_id/enable",
508
+ body: ["component_ids"],
509
+ source: "install_enable_route() -> install_enable_impl; body `component_ids`"
510
+ },
511
+ "install/uninstall": {
512
+ verb: "POST",
513
+ path: "/installs/:snapshot_id/uninstall",
514
+ body: ["component_ids"],
515
+ source: "install_uninstall_route() -> install_uninstall_impl; body `component_ids`"
516
+ },
517
+ "market/add": {
518
+ verb: "POST",
519
+ path: "/markets",
520
+ source: "market_add_route() -> market_add_impl"
521
+ },
522
+ "market/list": {
523
+ verb: "GET",
524
+ path: "/markets",
525
+ source: "market_list_route() -> market_list_impl"
526
+ },
527
+ "market/get": {
528
+ verb: "GET",
529
+ path: "/markets/:marketplace_id",
530
+ source: "market_get_route() -> market_get_impl"
531
+ },
532
+ "market/remove": {
533
+ verb: "POST",
534
+ path: "/markets/:marketplace_id/remove",
535
+ body: ["cascade"],
536
+ source: "market_remove_route() -> market_remove_impl; body `cascade` defaults to true"
537
+ },
538
+ "market/auto-update": {
539
+ verb: "POST",
540
+ path: "/markets/:marketplace_id/auto-update",
541
+ body: ["enabled"],
542
+ source: "market_auto_update_route() -> market_auto_update_impl; body `enabled` defaults to true"
543
+ },
544
+ "market/refresh": {
545
+ verb: "POST",
546
+ path: "/markets/:marketplace_id/refresh",
547
+ source: "market_refresh_route() -> market_refresh_impl"
548
+ },
549
+ "market/entry-import": {
550
+ verb: "POST",
551
+ path: "/markets/:marketplace_id/entries/:entry_name/import",
552
+ source: "market_entry_import_route() -> market_entry_import_impl"
553
+ },
554
+ "store/list": {
555
+ verb: "GET",
556
+ path: "/store",
557
+ source: "store_list_route() -> store_list_impl"
558
+ },
559
+ "store/install-entry": {
560
+ verb: "POST",
561
+ path: "/store/:marketplace_id/entries/:entry_name/install",
562
+ source: "store_install_entry_route() -> store_install_entry_impl"
563
+ }
564
+ };
565
+ /** Methods that are WebSocket-only by design — named so the error explains itself. */
566
+ const WS_ONLY_METHODS = /* @__PURE__ */ new Set([
567
+ "initialize",
568
+ "initialized",
569
+ "conversation/subscribe",
570
+ "conversation/unsubscribe",
571
+ "run/subscribe",
572
+ "run/unsubscribe"
573
+ ]);
574
+ var HttpTransport = class {
575
+ routes;
576
+ options;
577
+ closed = false;
578
+ constructor(options, routes = HTTP_ROUTES) {
579
+ this.options = options;
580
+ this.routes = routes;
581
+ }
582
+ /**
583
+ * No-op: the HTTP binding handshakes per call (`05` §2.1.1), so there is no
584
+ * connection to open. Kept for `Transport` compatibility.
585
+ */
586
+ async connect() {
587
+ this.closed = false;
588
+ }
589
+ /**
590
+ * Perform one business call over its own handshake.
591
+ *
592
+ * Throws `TransportError("send", …)` for a method with no HTTP binding —
593
+ * never a silent fallback to another binding.
594
+ */
595
+ async request(method, params) {
596
+ if (this.closed) throw new _flowy_agent_store_protocol.TransportError("connect", "http transport is closed");
597
+ const route = this.routes[method];
598
+ if (!route) {
599
+ const reason = WS_ONLY_METHODS.has(method) ? `"${method}" is WebSocket-only (doc 05 §2.1.1); use WebSocketTransport for subscriptions and live events` : `"${method}" has no HTTP binding in this SDK (doc 16 R2 route table)`;
600
+ throw new _flowy_agent_store_protocol.TransportError("send", reason);
601
+ }
602
+ const { path, query, body } = this.splitParams(route, params);
603
+ const connectionId = await this.openConnection();
604
+ const response = await this.fetchWithTimeout(route.verb, path, {
605
+ query,
606
+ body,
607
+ connectionId
608
+ });
609
+ return await this.readResult(response, method);
610
+ }
611
+ /**
612
+ * Not supported: HTTP carries no server-push. Throws instead of pretending.
613
+ */
614
+ notify(method, _params) {
615
+ throw new _flowy_agent_store_protocol.TransportError("send", `HTTP binding cannot notify ("${method}"): notifications are WebSocket-only (doc 05 §2.1.1)`);
616
+ }
617
+ /**
618
+ * Returns a no-op unsubscribe: this binding receives **no** notifications.
619
+ *
620
+ * Not equivalent to the WebSocket binding — callers that need live events
621
+ * must use `WebSocketTransport` (or run both).
622
+ */
623
+ onNotification(_listener) {
624
+ return () => void 0;
625
+ }
626
+ /** No-op: every call is independent, so nothing is held open. */
627
+ close() {
628
+ this.closed = true;
629
+ }
630
+ /**
631
+ * One-shot handshake: `POST /initialize` (connection id header) →
632
+ * `POST /initialized`. Returns the connection id.
633
+ *
634
+ * Public because host-side services that sit *outside* the protocol surface
635
+ * (`/api/fs/*`, the HTTP-only `POST /workspaces` register route) still need a
636
+ * ready connection id; they are not protocol methods, so they cannot go
637
+ * through `request()`.
638
+ */
639
+ async openConnection() {
640
+ const connectionId = (await this.fetchWithTimeout("POST", "/initialize", { body: {
641
+ protocol_version: PROTOCOL_VERSION,
642
+ client: this.options.client ?? {
643
+ name: "flowy-agent-store-client",
644
+ version: "0.1.0"
645
+ },
646
+ ...this.options.capabilities === void 0 ? {} : { capabilities: this.options.capabilities }
647
+ } })).headers.get(CONNECTION_HEADER);
648
+ if (!connectionId) throw new _flowy_agent_store_protocol.TransportError("connect", `handshake response is missing the ${CONNECTION_HEADER} header`, { retryable: true });
649
+ await this.fetchWithTimeout("POST", "/initialized", { connectionId });
650
+ return connectionId;
651
+ }
652
+ splitParams(route, params) {
653
+ const source = isRecord(params) ? params : {};
654
+ const pathParams = [...route.path.matchAll(/:([A-Za-z0-9_]+)/g)].map((match) => match[1]);
655
+ const path = route.path.replace(/:([A-Za-z0-9_]+)/g, (_full, name) => {
656
+ const value = source[name];
657
+ if (value === void 0 || value === null) throw new _flowy_agent_store_protocol.TransportError("send", `missing required path param "${name}" for ${route.verb} ${route.path}`);
658
+ return encodeURIComponent(String(value));
659
+ });
660
+ const query = {};
661
+ for (const key of route.query ?? []) {
662
+ const value = source[key];
663
+ if (value !== void 0 && value !== null) query[key] = String(value);
664
+ }
665
+ if (route.verb === "GET" || route.verb === "DELETE") return {
666
+ path,
667
+ query,
668
+ body: void 0
669
+ };
670
+ const carried = route.body ?? [];
671
+ const body = {};
672
+ for (const key of Object.keys(source)) {
673
+ if (pathParams.includes(key) || (route.query ?? []).includes(key)) continue;
674
+ if (carried.length > 0 && !carried.includes(key)) continue;
675
+ body[key] = source[key];
676
+ }
677
+ return {
678
+ path,
679
+ query,
680
+ body
681
+ };
682
+ }
683
+ async fetchWithTimeout(verb, path, request) {
684
+ const url = new URL(`${this.baseUrl()}${path}`);
685
+ for (const [key, value] of Object.entries(request.query ?? {})) url.searchParams.set(key, value);
686
+ const headers = { accept: "application/json" };
687
+ if (request.body !== void 0) headers["content-type"] = "application/json";
688
+ if (request.connectionId) headers[CONNECTION_HEADER] = request.connectionId;
689
+ if (this.options.token) headers.authorization = `Bearer ${this.options.token}`;
690
+ const controller = new AbortController();
691
+ const timeoutMs = this.options.requestTimeoutMs ?? 3e4;
692
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
693
+ try {
694
+ const fetchImpl = this.options.fetch ?? globalThis.fetch;
695
+ if (!fetchImpl) throw new _flowy_agent_store_protocol.TransportError("connect", "no fetch implementation available");
696
+ return await fetchImpl(url.toString(), {
697
+ method: verb,
698
+ headers,
699
+ body: request.body === void 0 ? void 0 : JSON.stringify(request.body),
700
+ signal: controller.signal
701
+ });
702
+ } catch (error) {
703
+ if (error instanceof _flowy_agent_store_protocol.TransportError) throw error;
704
+ const aborted = error?.name === "AbortError";
705
+ throw new _flowy_agent_store_protocol.TransportError("send", aborted ? `${verb} ${path} timed out after ${timeoutMs}ms` : `${verb} ${path} failed: ${String(error)}`, {
706
+ retryable: true,
707
+ cause: error
708
+ });
709
+ } finally {
710
+ clearTimeout(timer);
711
+ }
712
+ }
713
+ /** 2xx → result body; otherwise the server's wire error becomes an `AppServerError`. */
714
+ async readResult(response, method) {
715
+ let payload = void 0;
716
+ const text = await response.text();
717
+ if (text.length > 0) try {
718
+ payload = JSON.parse(text);
719
+ } catch {
720
+ if (response.ok) throw new _flowy_agent_store_protocol.TransportError("receive", `${method}: response is not JSON`, { retryable: true });
721
+ }
722
+ if (response.ok) return payload;
723
+ throw appServerErrorFromWire(payload, response.status, method);
724
+ }
725
+ baseUrl() {
726
+ return this.options.baseUrl.replace(/\/+$/, "").replace(/\/ws$/, "");
727
+ }
728
+ };
729
+ function isRecord(value) {
730
+ return typeof value === "object" && value !== null && !Array.isArray(value);
731
+ }
732
+ /**
733
+ * Turn an HTTP failure body into the SDK error model.
734
+ *
735
+ * Shared by this transport and by host-side helpers (webui `lib/client.ts`) so
736
+ * a second spelling of the wire-error mapping cannot drift. Two wire contracts
737
+ * reach this function, both of them `AppError` on the server:
738
+ *
739
+ * - the App Server emits `{code, message, retryable, details, request_id}`
740
+ * (`into_wire_error`), which is exactly the `AppServerError` shape;
741
+ * - the standalone host file service (`/api/fs/*`) emits the `ErrorResponse`
742
+ * envelope `{success: false, error, code, details?}` — same error, another
743
+ * spelling: `error` carries the human message, and there is no retry hint, so
744
+ * a 5xx status stays the retry signal.
745
+ *
746
+ * Anything else becomes a retryable-on-5xx `TransportError`.
747
+ */
748
+ function appServerErrorFromWire(payload, status, context = "request") {
749
+ if (isRecord(payload) && typeof payload.code === "string" && typeof payload.message === "string") return new _flowy_agent_store_protocol.AppServerError({
750
+ code: payload.code,
751
+ message: payload.message,
752
+ retryable: payload.retryable === true,
753
+ request_id: payload.request_id ?? null,
754
+ details: isRecord(payload.details) ? payload.details : {}
755
+ });
756
+ if (isRecord(payload) && payload.success === false && typeof payload.code === "string" && typeof payload.error === "string") return new _flowy_agent_store_protocol.AppServerError({
757
+ code: payload.code,
758
+ message: payload.error,
759
+ retryable: status >= 500,
760
+ request_id: null,
761
+ details: isRecord(payload.details) ? payload.details : {}
762
+ });
763
+ return new _flowy_agent_store_protocol.TransportError("receive", `${context}: HTTP ${status} without a wire error body`, { retryable: status >= 500 });
764
+ }
765
+ /** Exposed for tests and docs (R5): the verified method → route table. */
766
+ function httpRouteTable() {
767
+ return HTTP_ROUTES;
768
+ }
769
+ //#endregion
241
770
  //#region src/agents.ts
242
771
  var AgentClient = class {
243
772
  transport;
@@ -269,7 +798,9 @@ var ConversationClient = class {
269
798
  name: input.name,
270
799
  model,
271
800
  workspace: input.workspaceId ? { id: input.workspaceId } : void 0,
272
- reasoning_effort: input.reasoningEffort || void 0
801
+ reasoning_effort: input.reasoningEffort || void 0,
802
+ agent_id: input.agentId || void 0,
803
+ team_id: input.teamId || void 0
273
804
  });
274
805
  }
275
806
  update(conversationId, input) {
@@ -300,11 +831,35 @@ var ConversationClient = class {
300
831
  cursor: query.cursor
301
832
  });
302
833
  }
303
- send(conversationId, content, idempotencyKey) {
834
+ /**
835
+ * R15(W10):`attachments` 是**会话工作区内的绝对路径**(图片附件)。
836
+ * doc `27` §4.1:`mentions` 是**本轮挂载的技能**(`kind: "skill"`)——技能的正文与
837
+ * 不可变快照都随这一轮走;`agent` / `connector` 在 send 上没有载体,服务端会以
838
+ * `invalid_request` **明确拒绝**(不是静默不挂)。
839
+ *
840
+ * 两者缺省都不上 wire,保持老调用方的形状逐字不变;服务端只接受会话工作区内的真实
841
+ * 文件(越界 / 相对路径 / 不存在一律拒),准入见 `nomifun-app-server` 的
842
+ * `resolve_conversation_attachments` 与 `send_mention_skills`。
843
+ *
844
+ * 第 4 个参数同时接受旧的 `string[]`(附件)与选项对象——再堆一个位置参数会让调用点
845
+ * 变成一串没有名字的布尔/数组。
846
+ */
847
+ send(conversationId, content, idempotencyKey, options = {}) {
848
+ const attachments = Array.isArray(options) ? options : options.attachments ?? [];
849
+ const mentions = Array.isArray(options) ? [] : options.mentions ?? [];
850
+ const model = Array.isArray(options) ? void 0 : options.model;
851
+ const reasoningEffort = Array.isArray(options) ? void 0 : options.reasoningEffort;
304
852
  return this.transport.request("conversation/send", {
305
853
  conversation_id: conversationId,
306
854
  content,
307
- idempotency_key: idempotencyKey
855
+ idempotency_key: idempotencyKey,
856
+ ...attachments.length > 0 ? { attachments } : {},
857
+ ...mentions.length > 0 ? { mentions } : {},
858
+ ...model ? { model: {
859
+ provider_id: model.provider_id,
860
+ model: model.model
861
+ } } : {},
862
+ ...reasoningEffort ? { reasoning_effort: reasoningEffort } : {}
308
863
  });
309
864
  }
310
865
  cancel(conversationId) {
@@ -313,35 +868,92 @@ var ConversationClient = class {
313
868
  delete(conversationId) {
314
869
  return this.transport.request("conversation/delete", { conversation_id: conversationId });
315
870
  }
316
- async follow(conversationId) {
871
+ /**
872
+ * Subscribe to one conversation's realtime stream (doc `16` R1).
873
+ *
874
+ * `options.fetchMessages` is what makes auto catch-up possible: a detected
875
+ * sequence gap or a `conversation/resync-required` triggers one transcript
876
+ * fetch whose result is handed to `onBackfill`. Conversations have no event
877
+ * replay API (`05` §「V1 不提供 after_cursor 事件追平」), so the transcript is
878
+ * the recovery medium — unlike Runs, where `run/events` replays the events
879
+ * themselves.
880
+ */
881
+ async follow(conversationId, options = {}) {
317
882
  await this.transport.request("conversation/subscribe", { conversation_id: conversationId });
318
- return new ConversationSubscription(this.transport, conversationId);
883
+ return new ConversationSubscription(this.transport, conversationId, {
884
+ fetchMessages: (id) => this.messages({
885
+ conversationId: id,
886
+ pageSize: 50
887
+ }),
888
+ ...options
889
+ });
319
890
  }
320
891
  };
892
+ /** Events held before the first listener attaches (see `pendingLimit`). */
893
+ const DEFAULT_PENDING_LIMIT = 256;
321
894
  var ConversationSubscription = class {
322
895
  transport;
323
896
  conversationId;
897
+ options;
324
898
  events = /* @__PURE__ */ new Set();
325
899
  resyncs = /* @__PURE__ */ new Set();
900
+ errors = /* @__PURE__ */ new Set();
901
+ backfills = /* @__PURE__ */ new Set();
326
902
  closed = false;
327
903
  lastSeenSequence = 0;
328
904
  removeListener;
329
- constructor(transport, conversationId) {
905
+ /**
906
+ * `follow()` resolves as soon as the server acknowledged the subscription,
907
+ * but the caller attaches listeners one tick later. Events landing in that
908
+ * window used to be dropped silently; they are held here (oldest first) and
909
+ * flushed to the first `onEvent` listener.
910
+ */
911
+ pending = [];
912
+ pendingDropped = 0;
913
+ backfillInFlight = null;
914
+ constructor(transport, conversationId, options = {}) {
330
915
  this.transport = transport;
331
916
  this.conversationId = conversationId;
917
+ this.options = options;
332
918
  this.removeListener = transport.onNotification((notification) => this.dispatch(notification));
333
919
  }
334
920
  get lastSequence() {
335
921
  return this.lastSeenSequence;
336
922
  }
923
+ /** Events dropped because nobody was listening and the buffer was full. */
924
+ get droppedPendingCount() {
925
+ return this.pendingDropped;
926
+ }
337
927
  onEvent(listener) {
338
928
  this.events.add(listener);
929
+ if (this.events.size === 1 && this.pending.length > 0) {
930
+ const queued = this.pending;
931
+ this.pending = [];
932
+ for (const event of queued) this.deliver(event);
933
+ }
339
934
  return () => this.events.delete(listener);
340
935
  }
341
936
  onResync(listener) {
342
937
  this.resyncs.add(listener);
343
938
  return () => this.resyncs.delete(listener);
344
939
  }
940
+ /**
941
+ * Auto catch-up result (R1). Fires only when `autoResync` is on and the
942
+ * transcript fetch succeeded; the listener owns replacing the transcript.
943
+ */
944
+ onBackfill(listener) {
945
+ this.backfills.add(listener);
946
+ return () => this.backfills.delete(listener);
947
+ }
948
+ /**
949
+ * Failures that used to be swallowed: the catch-up fetch, and a failed
950
+ * re-subscribe during `rearm()`. Listener isolation keeps one bad listener
951
+ * from hiding the error from the others.
952
+ */
953
+ onError(listener) {
954
+ this.errors.add(listener);
955
+ return () => this.errors.delete(listener);
956
+ }
345
957
  async close() {
346
958
  if (this.closed) return;
347
959
  this.closed = true;
@@ -349,6 +961,9 @@ var ConversationSubscription = class {
349
961
  this.removeListener = null;
350
962
  this.events.clear();
351
963
  this.resyncs.clear();
964
+ this.errors.clear();
965
+ this.backfills.clear();
966
+ this.pending = [];
352
967
  try {
353
968
  await this.transport.request("conversation/unsubscribe", { conversation_id: this.conversationId });
354
969
  } catch {}
@@ -356,35 +971,99 @@ var ConversationSubscription = class {
356
971
  /**
357
972
  * Re-arm after a reconnect (docs/agent-store/16 T8): re-register the
358
973
  * notification listener, reset the cursor and re-issue
359
- * `conversation/subscribe`. This subscription has no event-replay API, so the
360
- * caller must still backfill the transcript for the outage window
361
- * (`conversation/messages`). Call it once the handshake completed; a no-op
362
- * once closed.
974
+ * `conversation/subscribe`. The server restarts a conversation's sequence at
975
+ * 1 for a fresh subscription, which is exactly why the cursor resets. On a
976
+ * failed re-subscribe the error reaches `onError` and the caller can still
977
+ * backfill the outage window via `conversation/messages`.
363
978
  */
364
979
  async rearm() {
365
980
  if (this.closed) return;
366
981
  this.removeListener?.();
367
982
  this.removeListener = this.transport.onNotification((notification) => this.dispatch(notification));
368
983
  this.lastSeenSequence = 0;
369
- await this.transport.request("conversation/subscribe", { conversation_id: this.conversationId });
984
+ try {
985
+ await this.transport.request("conversation/subscribe", { conversation_id: this.conversationId });
986
+ } catch (error) {
987
+ this.emitError(error);
988
+ throw error;
989
+ }
370
990
  }
371
991
  dispatch(notification) {
372
992
  if (notification.method === "conversation/event") {
373
993
  const event = notification.params;
374
- if (event.conversation_id !== this.conversationId || event.sequence <= this.lastSeenSequence) return;
994
+ if (event.conversation_id !== this.conversationId) return;
995
+ if (!Number.isFinite(event.sequence)) return;
996
+ if (event.sequence <= this.lastSeenSequence) return;
997
+ const gap = this.lastSeenSequence > 0 && event.sequence > this.lastSeenSequence + 1;
375
998
  this.lastSeenSequence = event.sequence;
376
- for (const listener of [...this.events]) try {
377
- listener(event);
378
- } catch {}
999
+ if (this.events.size === 0) this.buffer(event);
1000
+ else this.deliver(event);
1001
+ if (gap) {
1002
+ this.emitResync("gap");
1003
+ this.requestBackfill("gap");
1004
+ }
379
1005
  return;
380
1006
  }
381
1007
  if (notification.method === "conversation/resync-required") {
382
1008
  if (!notification.params.conversation_ids.includes(this.conversationId)) return;
383
- for (const listener of [...this.resyncs]) try {
384
- listener(notification.params.reason);
385
- } catch {}
1009
+ this.emitResync(notification.params.reason);
1010
+ this.requestBackfill(notification.params.reason);
1011
+ }
1012
+ }
1013
+ buffer(event) {
1014
+ const limit = this.options.pendingLimit ?? DEFAULT_PENDING_LIMIT;
1015
+ this.pending.push(event);
1016
+ while (this.pending.length > limit) {
1017
+ this.pending.shift();
1018
+ this.pendingDropped += 1;
386
1019
  }
387
1020
  }
1021
+ deliver(event) {
1022
+ for (const listener of [...this.events]) try {
1023
+ listener(event);
1024
+ } catch {}
1025
+ }
1026
+ emitResync(reason) {
1027
+ for (const listener of [...this.resyncs]) try {
1028
+ listener(reason);
1029
+ } catch {}
1030
+ }
1031
+ emitError(error) {
1032
+ for (const listener of [...this.errors]) try {
1033
+ listener(error);
1034
+ } catch {}
1035
+ }
1036
+ /**
1037
+ * One in-flight catch-up at a time: a burst of resync signals collapses into
1038
+ * a single transcript fetch (the fetch itself returns the newest page, so the
1039
+ * result supersedes every signal that arrived before it).
1040
+ */
1041
+ requestBackfill(reason) {
1042
+ if (this.closed || this.options.autoResync === false) return;
1043
+ const fetchMessages = this.options.fetchMessages;
1044
+ if (!fetchMessages || this.backfillInFlight) return;
1045
+ const task = (async () => {
1046
+ try {
1047
+ const page = await fetchMessages(this.conversationId);
1048
+ if (this.closed) return;
1049
+ const backfill = {
1050
+ conversationId: this.conversationId,
1051
+ reason,
1052
+ messages: page?.items ?? [],
1053
+ hasMore: page?.has_more === true
1054
+ };
1055
+ for (const listener of [...this.backfills]) try {
1056
+ listener(backfill);
1057
+ } catch {}
1058
+ } catch (error) {
1059
+ this.emitError(error);
1060
+ }
1061
+ })();
1062
+ this.backfillInFlight = task;
1063
+ task.finally(() => {
1064
+ if (this.backfillInFlight === task) this.backfillInFlight = null;
1065
+ });
1066
+ }
388
1067
  };
389
1068
  //#endregion
390
1069
  //#region src/connectors.ts
@@ -405,7 +1084,19 @@ var ConnectorClient = class {
405
1084
  status(connectorId) {
406
1085
  return this.transport.request("connector/status", { connector_id: connectorId });
407
1086
  }
408
- /** Run a connection probe; the server persists the result. */
1087
+ /**
1088
+ * Run a connection probe and report what the connector currently offers —
1089
+ * including each tool's `input_schema`.
1090
+ *
1091
+ * It really connects: a stdio connector gets its child process spawned, an
1092
+ * HTTP/SSE one gets `initialize` + `tools/list`. The result is **persisted**,
1093
+ * so this is also what refreshes the tool list `get()` reads back.
1094
+ *
1095
+ * Named `test` and not `probe` on purpose: this repo's split is `test` for the
1096
+ * action (wire `connector/test`, `test_connection`) and `probe` for its
1097
+ * artifact (`ConnectorProbeResult`, `probe_status`), and every method here is
1098
+ * the last segment of its wire method.
1099
+ */
409
1100
  test(connectorId) {
410
1101
  return this.transport.request("connector/test", { connector_id: connectorId });
411
1102
  }
@@ -424,6 +1115,36 @@ var ConnectorClient = class {
424
1115
  logout(connectorId) {
425
1116
  return this.transport.request("connector/auth/logout", { connector_id: connectorId }).then(() => void 0);
426
1117
  }
1118
+ /**
1119
+ * Run one tool on a registered connector, through the host's own connection.
1120
+ *
1121
+ * The host holds the transport, its headers and its OAuth token; this sends a
1122
+ * tool name and an argument object and nothing else — you cannot name a URL,
1123
+ * a command or a header. Whether the pair is callable at all is the host's
1124
+ * `[connector_proxy]` policy: once its operator turns the proxy on, the
1125
+ * enabled connectors are callable, and `allow` / `deny` are that operator's
1126
+ * optional narrowing and subtraction. So `policy_denied` means either that
1127
+ * the host never turned the proxy on, or that this pair was narrowed out or
1128
+ * explicitly denied — not that a tool name was misspelled in a list you were
1129
+ * supposed to maintain.
1130
+ *
1131
+ * Arguments are passed through verbatim (there is no client-side schema
1132
+ * check); `get()` / `test()` return each tool's `input_schema` so you can see
1133
+ * what it takes, and a parameter the server rejects comes back as
1134
+ * `is_error: true`, not as a rejected promise.
1135
+ *
1136
+ * Resolves even when the tool itself failed — check `is_error`. It rejects
1137
+ * only when the call never reached the tool: `connector_call_timeout`,
1138
+ * `connector_call_failed`, `response_too_large`, `connector_unavailable`,
1139
+ * `policy_denied`, `not_found`.
1140
+ */
1141
+ call(connectorId, tool, args = {}) {
1142
+ return this.transport.request("connector/call", {
1143
+ connector_id: connectorId,
1144
+ tool,
1145
+ arguments: args
1146
+ });
1147
+ }
427
1148
  };
428
1149
  //#endregion
429
1150
  //#region src/runs.ts
@@ -440,6 +1161,18 @@ var RunClient = class {
440
1161
  agent(input) {
441
1162
  return this.transport.request("agent/run", toWire(input));
442
1163
  }
1164
+ /**
1165
+ * Start a Team run (`16` §7 决策 3): the server creates the Leader
1166
+ * Conversation, materializes/binds the Team's execution template and returns
1167
+ * the public run id of the execution the Leader started.
1168
+ *
1169
+ * The receipt is `TeamRunReceipt`, not `RunReceipt` — a Team Run has no lead
1170
+ * preset revision/digest to report. Member pool and concurrency limits are not
1171
+ * inputs; sending `planning` is rejected as `invalid_request`.
1172
+ */
1173
+ team(input) {
1174
+ return this.transport.request("team/run", toTeamWire(input));
1175
+ }
443
1176
  /** Read the authoritative run state. */
444
1177
  get(runId) {
445
1178
  return this.transport.request("run/get", { run_id: runId });
@@ -448,6 +1181,14 @@ var RunClient = class {
448
1181
  result(runId) {
449
1182
  return this.transport.request("run/result", { run_id: runId });
450
1183
  }
1184
+ /**
1185
+ * Read the authoritative plan / step snapshot (W4 / W6, resolves D-W6-1):
1186
+ * titles, statuses, retries with their reason, errors and timings — none of
1187
+ * which the append-only event log carries.
1188
+ */
1189
+ plan(runId) {
1190
+ return this.transport.request("run/plan", { run_id: runId });
1191
+ }
451
1192
  /** Replay persisted events after a cursor. */
452
1193
  events(query) {
453
1194
  return this.transport.request("run/events", {
@@ -478,6 +1219,26 @@ var RunClient = class {
478
1219
  idempotency_key: input.idempotencyKey
479
1220
  });
480
1221
  }
1222
+ /**
1223
+ * Answer the pending decision of a `waiting_input` attempt.
1224
+ *
1225
+ * The three `expected*Version` tokens are mandatory CAS inputs, normally the
1226
+ * ones projected on the pending `approval.requested` event. The server passes
1227
+ * them straight to the engine's single answer gate, so a stale token is a
1228
+ * `conflict`, never a silent overwrite. There is no `always_allow` here: the
1229
+ * desktop confirmation route's approve-all flag is not part of this protocol.
1230
+ */
1231
+ answerDecision(input) {
1232
+ return this.transport.request("run/answer-decision", {
1233
+ run_id: input.runId,
1234
+ step_id: input.stepId,
1235
+ attempt_id: input.attemptId,
1236
+ answer: input.answer,
1237
+ expected_execution_version: input.expectedExecutionVersion,
1238
+ expected_step_version: input.expectedStepVersion,
1239
+ expected_attempt_version: input.expectedAttemptVersion
1240
+ });
1241
+ }
481
1242
  /** Subscribe to best-effort realtime events for one run. */
482
1243
  async follow(runId, options) {
483
1244
  const params = { run_id: runId };
@@ -669,7 +1430,23 @@ function toWire(input) {
669
1430
  steps: input.steps,
670
1431
  command_id: input.commandId,
671
1432
  idempotency_key: input.idempotencyKey,
672
- mentions: input.mentions
1433
+ mentions: input.mentions,
1434
+ model: input.model ? {
1435
+ provider_id: input.model.provider_id,
1436
+ model: input.model.model
1437
+ } : void 0,
1438
+ reasoning_effort: input.reasoningEffort || void 0
1439
+ };
1440
+ }
1441
+ function toTeamWire(input) {
1442
+ return {
1443
+ team_id: input.teamId,
1444
+ team_version: input.teamVersion,
1445
+ goal: input.goal,
1446
+ input: input.input,
1447
+ workspace: input.workspaceId ? { id: input.workspaceId } : void 0,
1448
+ command_id: input.commandId,
1449
+ idempotency_key: input.idempotencyKey
673
1450
  };
674
1451
  }
675
1452
  //#endregion
@@ -687,6 +1464,309 @@ var SkillClient = class {
687
1464
  get(skillId) {
688
1465
  return this.transport.request("skill/get", { skill_id: skillId });
689
1466
  }
1467
+ /**
1468
+ * Every readable file inside a Skill's directory, with a tree digest.
1469
+ *
1470
+ * This is the only way to learn what a Skill actually ships: `get()` returns
1471
+ * a bounded summary of `SKILL.md` and says nothing about the `references/`,
1472
+ * `scripts/`, `templates/` and `assets/` beside it. Check
1473
+ * `capabilities.skill_files` first — a host may wire the catalog without
1474
+ * this face, in which case it answers `unsupported_operation`.
1475
+ */
1476
+ files(skillId) {
1477
+ return this.transport.request("skill/files", { skill_id: skillId });
1478
+ }
1479
+ /**
1480
+ * One skill file's bytes, over the WebSocket binding.
1481
+ *
1482
+ * The wire carries base64 because JSON has no byte string, so this decodes
1483
+ * back to `Uint8Array` for you. The HTTP route
1484
+ * (`GET /api/app-server/skills/{id}/files/{path}`) returns the raw body
1485
+ * instead, but that is deliberately not on the typed client's JSON
1486
+ * transport — use this method, or `fetch` the route directly if you are on a
1487
+ * host token.
1488
+ */
1489
+ async readFile(skillId, path) {
1490
+ return decodeBase64((await this.transport.request("skill/file", {
1491
+ skill_id: skillId,
1492
+ path
1493
+ })).content);
1494
+ }
1495
+ /** Same as {@link readFile}, but also returns the server's content type. */
1496
+ readFileWithType(skillId, path) {
1497
+ return this.transport.request("skill/file", {
1498
+ skill_id: skillId,
1499
+ path
1500
+ });
1501
+ }
1502
+ };
1503
+ /**
1504
+ * Decode base64 to bytes.
1505
+ *
1506
+ * `atob` is used when present (browsers, Bun, Node 16+) and a manual decode
1507
+ * otherwise, so the package keeps working on a bare Node without a DOM lib.
1508
+ */
1509
+ function decodeBase64(content) {
1510
+ if (typeof atob === "function") {
1511
+ const binary = atob(content);
1512
+ const bytes = new Uint8Array(binary.length);
1513
+ for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
1514
+ return bytes;
1515
+ }
1516
+ const bufferCtor = globalThis.Buffer;
1517
+ if (bufferCtor) return bufferCtor.from(content, "base64");
1518
+ throw new Error("no base64 decoder available in this environment");
1519
+ }
1520
+ //#endregion
1521
+ //#region src/store.ts
1522
+ var StoreError = class extends Error {
1523
+ code;
1524
+ constructor(code, message) {
1525
+ super(message);
1526
+ this.code = code;
1527
+ this.name = "StoreError";
1528
+ }
1529
+ };
1530
+ const DEFAULT_READY_TIMEOUT_MS = 3e4;
1531
+ const DEFAULT_READY_POLL_MS = 400;
1532
+ const DEFAULT_READY_POLL_MAX_MS = 4e3;
1533
+ /** Every string a `LocalizedText` carries, for haystack building. */
1534
+ function localizedValues(text) {
1535
+ if (typeof text === "string") return [text];
1536
+ if (!text || typeof text !== "object") return [];
1537
+ return Object.values(text).filter((value) => typeof value === "string");
1538
+ }
1539
+ function haystack(item) {
1540
+ return [
1541
+ item.entry_name,
1542
+ item.name,
1543
+ item.id,
1544
+ item.description ?? "",
1545
+ item.version,
1546
+ ...localizedValues(item.display_name),
1547
+ ...localizedValues(item.display_description),
1548
+ ...localizedValues(item.profession),
1549
+ ...(item.tags ?? []).flatMap(localizedValues)
1550
+ ].join("\n").toLowerCase();
1551
+ }
1552
+ function abortableDelay(ms, signal) {
1553
+ return new Promise((resolve, reject) => {
1554
+ if (signal?.aborted) {
1555
+ reject(new StoreError("aborted", "the operation was aborted"));
1556
+ return;
1557
+ }
1558
+ const timer = setTimeout(() => {
1559
+ signal?.removeEventListener("abort", onAbort);
1560
+ resolve();
1561
+ }, ms);
1562
+ const onAbort = () => {
1563
+ clearTimeout(timer);
1564
+ reject(new StoreError("aborted", "the operation was aborted"));
1565
+ };
1566
+ signal?.addEventListener("abort", onAbort, { once: true });
1567
+ });
1568
+ }
1569
+ var StoreClient = class {
1570
+ host;
1571
+ readyTimeoutMs;
1572
+ readyPollMs;
1573
+ readyPollMaxMs;
1574
+ constructor(host, options = {}) {
1575
+ this.host = host;
1576
+ this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
1577
+ this.readyPollMs = options.readyPollMs ?? DEFAULT_READY_POLL_MS;
1578
+ this.readyPollMaxMs = options.readyPollMaxMs ?? DEFAULT_READY_POLL_MAX_MS;
1579
+ }
1580
+ /** Every item across enabled marketplaces, with install state. */
1581
+ async list() {
1582
+ return (await this.host.listStore()).items;
1583
+ }
1584
+ /** Case-insensitive substring search over the fields a user can see. */
1585
+ async search(query, filter = {}) {
1586
+ const needle = query.trim().toLowerCase();
1587
+ return (await this.list()).filter((item) => {
1588
+ if (filter.kind && item.kind !== filter.kind) return false;
1589
+ if (!needle) return true;
1590
+ return haystack(item).includes(needle);
1591
+ });
1592
+ }
1593
+ /** Items currently installed on this host. */
1594
+ async installed() {
1595
+ return (await this.list()).filter((item) => item.installed);
1596
+ }
1597
+ /**
1598
+ * Installed items whose marketplace offers a different version.
1599
+ *
1600
+ * Both conditions matter: `update_available` is computed from the imported
1601
+ * snapshot even when nothing is installed, so filtering on it alone would
1602
+ * report an "update" for an entry the user has never installed.
1603
+ */
1604
+ async checkUpdates() {
1605
+ return (await this.list()).filter((item) => item.installed && item.update_available);
1606
+ }
1607
+ /**
1608
+ * What a caller can offer for an item's pending update.
1609
+ *
1610
+ * `"none"` means there is nothing to do; `"uninstall_reinstall"` means the
1611
+ * entry is installed at a different version and the only path the wire offers
1612
+ * is to release it and install again (the version-aware re-import then picks
1613
+ * up the current version). `"unknown"` is returned rather than guessing when
1614
+ * the item carries no snapshot to release.
1615
+ */
1616
+ updateHint(item) {
1617
+ if (!item.installed || !item.update_available) return "none";
1618
+ return item.snapshot_id ? "uninstall_reinstall" : "unknown";
1619
+ }
1620
+ /**
1621
+ * Import (when needed) and install one store item, then wait until it is
1622
+ * usable.
1623
+ */
1624
+ async install(item, options = {}) {
1625
+ this.assertUsable(item, options.signal);
1626
+ const result = await this.host.installStoreEntry(item.marketplace_id, item.entry_name);
1627
+ const components = result.outcomes ?? [];
1628
+ const outcome = {
1629
+ snapshotId: result.snapshot_id,
1630
+ reused: result.reused,
1631
+ components,
1632
+ ok: result.errors.length === 0 && components.every((component) => component.ok)
1633
+ };
1634
+ if (options.waitForReady === false) return outcome;
1635
+ return this.awaitReady(outcome, options);
1636
+ }
1637
+ /**
1638
+ * Release an item's runtime artifacts and clear its install record.
1639
+ *
1640
+ * The server only clears the record for components it actually released, so a
1641
+ * partial failure leaves `ok: false` with the failing component named — and
1642
+ * the item stays installed, which is what makes a retry meaningful.
1643
+ */
1644
+ async uninstall(item, options = {}) {
1645
+ const snapshotId = this.requireSnapshot(item);
1646
+ const componentIds = options.componentIds ?? await this.installedComponentIds(snapshotId);
1647
+ if (componentIds.length === 0) return {
1648
+ snapshotId,
1649
+ reused: true,
1650
+ components: [],
1651
+ ok: true
1652
+ };
1653
+ const status = await this.host.uninstallInstall(snapshotId, componentIds);
1654
+ return this.outcomeFromStatus(snapshotId, status, false);
1655
+ }
1656
+ /**
1657
+ * Switch an item's components on or off.
1658
+ *
1659
+ * Idempotent: the server sets the state it is asked for instead of toggling.
1660
+ * A skill reports `skill_disable_flag_only` because the skill corpus has no
1661
+ * enable state — that code is passed through, not swallowed, so a caller can
1662
+ * tell "switched off" from "marked in the catalogue".
1663
+ */
1664
+ async setEnabled(item, enabled, options = {}) {
1665
+ const snapshotId = this.requireSnapshot(item);
1666
+ const componentIds = options.componentIds ?? await this.installedComponentIds(snapshotId);
1667
+ if (componentIds.length === 0) return {
1668
+ snapshotId,
1669
+ reused: true,
1670
+ components: [],
1671
+ ok: true
1672
+ };
1673
+ const status = enabled ? await this.host.enableInstall(snapshotId, componentIds) : await this.host.disableInstall(snapshotId, componentIds);
1674
+ return this.outcomeFromStatus(snapshotId, status, false);
1675
+ }
1676
+ assertUsable(item, signal) {
1677
+ if (signal?.aborted) throw new StoreError("aborted", "the operation was aborted before it started");
1678
+ if (item.blocked_reason) throw new StoreError("item_blocked", item.blocked_reason);
1679
+ }
1680
+ requireSnapshot(item) {
1681
+ const snapshotId = item.snapshot_id;
1682
+ if (!snapshotId) throw new StoreError("not_installed", `store item ${item.id} has no imported snapshot to act on`);
1683
+ return snapshotId;
1684
+ }
1685
+ async installedComponentIds(snapshotId) {
1686
+ return (await this.host.getInstallStatus(snapshotId)).components.filter((component) => component.state !== "not-installed").map((component) => component.id);
1687
+ }
1688
+ outcomeFromStatus(snapshotId, status, reused) {
1689
+ const components = status.outcomes ?? [];
1690
+ return {
1691
+ snapshotId,
1692
+ reused,
1693
+ components,
1694
+ ok: (status.errors ?? []).length === 0 && components.every((component) => component.ok)
1695
+ };
1696
+ }
1697
+ /**
1698
+ * Poll until every component of the snapshot is usable.
1699
+ *
1700
+ * A timeout does **not** discard the install: the caller gets the successful
1701
+ * install plus `ready: false` and `readyIssue: "ready_timeout"`, so a slow
1702
+ * connector never turns into "the install failed".
1703
+ */
1704
+ async awaitReady(outcome, options) {
1705
+ const snapshotId = outcome.snapshotId;
1706
+ if (!snapshotId) return outcome;
1707
+ const status = await this.host.getInstallStatus(snapshotId);
1708
+ const connectors = status.components.filter((component) => component.kind === "connector" && component.state !== "not-installed");
1709
+ if (connectors.length > 0) await this.host.enableInstall(snapshotId, connectors.map((component) => component.id));
1710
+ const deadline = Date.now() + (options.timeoutMs ?? this.readyTimeoutMs);
1711
+ let interval = this.readyPollMs;
1712
+ let last = status.components;
1713
+ for (;;) {
1714
+ const blocked = (await Promise.all(last.filter((component) => component.state !== "not-installed").map(async (component) => ({
1715
+ component,
1716
+ verdict: await this.readiness(component)
1717
+ })))).find((entry) => !entry.verdict.ready);
1718
+ if (!blocked) return {
1719
+ ...outcome,
1720
+ ready: true
1721
+ };
1722
+ if (!blocked.verdict.ready && blocked.verdict.terminal) return {
1723
+ ...outcome,
1724
+ ready: false,
1725
+ readyIssue: blocked.verdict.terminal,
1726
+ readyComponentId: blocked.component.id
1727
+ };
1728
+ if (Date.now() >= deadline) return {
1729
+ ...outcome,
1730
+ ready: false,
1731
+ readyIssue: "ready_timeout",
1732
+ readyComponentId: blocked.component.id
1733
+ };
1734
+ await abortableDelay(interval, options.signal);
1735
+ interval = Math.min(interval * 2, this.readyPollMaxMs);
1736
+ last = (await this.host.getInstallStatus(snapshotId)).components;
1737
+ }
1738
+ }
1739
+ /**
1740
+ * Is this one component usable yet?
1741
+ *
1742
+ * Each kind answers with the narrowest read the protocol already offers. An
1743
+ * unknown kind is reported ready rather than blocking: this layer cannot judge
1744
+ * a component it does not understand, and a false timeout on a future kind
1745
+ * would be worse than passing it through.
1746
+ */
1747
+ async readiness(component) {
1748
+ try {
1749
+ switch (component.kind) {
1750
+ case "skill": return (await this.host.skills.list()).some((skill) => skill.name === component.name) ? { ready: true } : { ready: false };
1751
+ case "agent": return (await this.host.agents.get(component.id)).preset_id ? { ready: true } : { ready: false };
1752
+ case "team":
1753
+ await this.host.teams.get(component.id);
1754
+ return { ready: true };
1755
+ case "connector": {
1756
+ if ((await this.host.connectors.test(component.id)).success) return { ready: true };
1757
+ const status = await this.host.connectors.status(component.id);
1758
+ if (status.status === "authorization_required" || status.status === "reauthorization_required") return {
1759
+ ready: false,
1760
+ terminal: "authorization_required"
1761
+ };
1762
+ return { ready: false };
1763
+ }
1764
+ default: return { ready: true };
1765
+ }
1766
+ } catch {
1767
+ return { ready: false };
1768
+ }
1769
+ }
690
1770
  };
691
1771
  //#endregion
692
1772
  //#region src/teams.ts
@@ -776,6 +1856,12 @@ var AppServerClient = class {
776
1856
  teams;
777
1857
  /** Public model directory (`models/list`, REQ-PAR-05b). */
778
1858
  models;
1859
+ /**
1860
+ * Agent Store lifecycle as one state machine: search → install (wait until
1861
+ * usable) → enable/disable → uninstall. Composes the flat methods below; it
1862
+ * adds no wire surface.
1863
+ */
1864
+ store;
779
1865
  clientInfo;
780
1866
  capabilities;
781
1867
  initializeResult = null;
@@ -794,6 +1880,7 @@ var AppServerClient = class {
794
1880
  this.agents = new AgentClient(this.transport);
795
1881
  this.teams = new TeamClient(this.transport);
796
1882
  this.models = new ModelClient(this.transport);
1883
+ this.store = new StoreClient(this, options.store);
797
1884
  this.bridgeNotifications();
798
1885
  }
799
1886
  /**
@@ -863,7 +1950,14 @@ var AppServerClient = class {
863
1950
  async getInstallStatus(snapshotId) {
864
1951
  return this.transport.request("install/status", { snapshot_id: snapshotId });
865
1952
  }
866
- /** Disable installed components (runtime artifacts stay). */
1953
+ /**
1954
+ * Disable installed components.
1955
+ *
1956
+ * The runtime state moves with the flag — a connector's MCP server is switched
1957
+ * off, an expert's Preset is disabled — while the artifacts stay on disk. A
1958
+ * skill is the documented exception: the corpus has no enable state, so it
1959
+ * reports `skill_disable_flag_only` and the flag stays a catalogue marker.
1960
+ */
867
1961
  async disableInstall(snapshotId, componentIds) {
868
1962
  return this.transport.request("install/disable", {
869
1963
  snapshot_id: snapshotId,
@@ -1331,14 +2425,19 @@ exports.ConversationClient = ConversationClient;
1331
2425
  exports.ConversationHandle = ConversationHandle;
1332
2426
  exports.ConversationSubscription = ConversationSubscription;
1333
2427
  exports.EventSubscription = EventSubscription;
2428
+ exports.HttpTransport = HttpTransport;
1334
2429
  exports.ModelClient = ModelClient;
1335
2430
  exports.RunClient = RunClient;
1336
2431
  exports.SkillClient = SkillClient;
2432
+ exports.StoreClient = StoreClient;
2433
+ exports.StoreError = StoreError;
1337
2434
  exports.TeamClient = TeamClient;
1338
2435
  exports.WebSocketTransport = WebSocketTransport;
1339
2436
  exports.WorkspaceClient = WorkspaceClient;
1340
2437
  exports.aggregateTurnResult = aggregateTurnResult;
2438
+ exports.appServerErrorFromWire = appServerErrorFromWire;
1341
2439
  exports.conversationMessages = conversationMessages;
2440
+ exports.httpRouteTable = httpRouteTable;
1342
2441
  exports.isLoopbackUrl = isLoopbackUrl;
1343
2442
  exports.launchRun = launchRun;
1344
2443
  exports.withRetry = withRetry;