Subagent bound thread

Tổng quan

Tính năng này cho phép người dùng tương tác với subagent được spawn trực tiếp bên trong thread Discord.

Thay vì chỉ chờ tóm tắt hoàn thành trong phiên cha, người dùng có thể di chuyển vào thread chuyên dụng định tuyến message đến phiên subagent được spawn. Phản hồi được gửi trong thread với persona bound thread.

Triển khai được chia giữa hook vòng đời cốt lõi độc lập kênh và hành vi extension riêng Discord.

Mục tiêu

• Cho phép cuộc trò chuyện thread trực tiếp với phiên subagent được spawn.
• Giữ điều phối subagent mặc định độc lập kênh.
• Hỗ trợ cả tạo thread tự động khi spawn và điều khiển focus thủ công.
• Cung cấp dọn dẹp có thể dự đoán khi hoàn thành, kill, timeout và thay đổi vòng đời thread.
• Giữ hành vi có thể cấu hình với mặc định toàn cầu cộng ghi đè kênh và tài khoản.

Ngoài phạm vi

• Tính năng giao thức ACP mới.
• Triển khai binding thread không phải Discord trong tài liệu này.
• Tài khoản bot mới hoặc thay đổi định danh Discord cấp ứng dụng.

Điều gì đã được cung cấp

• sessions_spawn hỗ trợ thread: true và mode: "run" | "session".
• Luồng spawn hỗ trợ phiên bound thread lâu dài.
• Manager binding thread Discord hỗ trợ bind, unbind, sweep TTL và lưu trữ.
• Hook vòng đời plugin cho subagent:
  • subagent_spawning
  • subagent_spawned
  • subagent_delivery_target
  • subagent_ended
• Extension Discord triển khai bind tự động thread, ghi đè mục tiêu phân phối và unbind khi kết thúc.
• Lệnh text cho điều khiển thủ công:
  • /focus
  • /unfocus
  • /agents
  • /session ttl
• Điều khiển kích hoạt và TTL phạm vi toàn cầu và Discord, bao gồm kill switch toàn cầu.

Khái niệm cốt lõi

Chế độ spawn

• mode: "run"
  • vòng đời tác vụ một
  • luồng công bố hoàn thành
• mode: "session"
  • phiên bound thread lâu dài
  • hỗ trợ message người dùng theo dõi trong thread

Hành vi chế độ mặc định:

• nếu thread: true và mode bỏ qua, mode mặc định về "session"
• nếu không mode mặc định về "run"

Ràng buộc:

• mode: "session" yêu cầu thread: true

Mô hình mục tiêu binding thread

Binding là mục tiêu chung, không chỉ subagent.

• targetKind: "subagent" | "acp"
• targetSessionKey: string

Điều này cho phép nguyên thủy routing giống nhau hỗ trợ binding ACP/phiên cũng vậy.

Manager binding thread

Manager chịu trách nhiệm cho:

• binding hoặc tạo thread cho mục tiêu phiên
• unbinding bằng thread hoặc bằng phiên mục tiêu
• quản lý tái sử dụng webhook và ngăn chặn echo webhook mới unbind
• unbind dựa trên TTL và dọn dẹp thread cũ
• load và lưu lưu trữ

Kiến trúc

Ranh giới cốt lõi và extension

Cốt lõi (src/agents/*) không phụ thuộc trực tiếp vào nội bộ routing Discord.

Cốt lõi phát ra ý định vòng đời qua hook plugin.

Extension Discord (extensions/discord/src/subagent-hooks.ts) triển khai hành vi riêng Discord:

• chuẩn bị bind thread trước spawn
• ghi đè mục tiêu phân phối hoàn thành sang thread bound
• unbind khi subagent kết thúc

Luồng hook plugin

1. subagent_spawning
   • trước khi run bắt đầu
   • có thể chặn spawn với status: "error"
   • được sử dụng để chuẩn bị binding thread khi thread: true
2. subagent_spawned
   • sự kiện đăng ký sau run
3. subagent_delivery_target
   • hook ghi đè routing hoàn thành
   • có thể chuyển hướng phân phối hoàn thành sang nguồn thread bound Discord
4. subagent_ended
   • tín hiệu dọn dẹp và unbind

Hợp đồng chuẩn hóa Account ID

Trạng thái binding thread và routing phải sử dụng một trừu tượng id tài khoản chuẩn.

Đặc tả:

• Giới thiệu module id tài khoản được chia sẻ (đề xuất: src/routing/account-id.ts) và dừng định nghĩa normalizer local.
• Hiển thị hai helper rõ ràng:
  • normalizeAccountId(value): string
    • trả về id chuẩn, mặc định (mặc định hiện tại là default)
    • sử dụng cho key bản đồ, đăng ký và lookup manager, key lưu trữ, key routing
  • normalizeOptionalAccountId(value): string | undefined
    • trả về id chuẩn khi có mặt, undefined khi vắng mặt
    • sử dụng cho trường ngữ cảnh tùy chọn đến và logic hợp nhất
• Không triển khai chuẩn hóa tài khoản ad hoc trong module tính năng.
  • Điều này bao gồm logic trim, toLowerCase hoặc mặc định trong hàm helper local.
• Bất kỳ bản đồ nào được đặt key bằng id tài khoản chỉ phải chấp nhận id chuẩn từ helper được chia sẻ.
• Payload hook và ngữ cảnh phân phối nên mang id tài khoản tùy chọn raw và chuẩn hóa chỉ ở ranh giới module.

Hàng rào di chuyển:

• Thay thế normalizer trùng lặp trong routing, payload phản hồi, ngữ cảnh lệnh và helper provider bằng helper được chia sẻ.
• Thêm test hợp đồng khẳng định hành vi chuẩn hóa giống nhau qua:
  • giải quyết route
  • lookup manager binding thread
  • lọc mục tiêu phân phối phản hồi
  • hợp nhất ngữ cảnh run lệnh

Lưu trữ và trạng thái

Đường dẫn trạng thái binding:

• ${stateDir}/discord/thread-bindings.json

Shape bản ghi chứa:

• tài khoản, kênh, thread
• loại mục tiêu và key phiên mục tiêu
• metadata nhãn agent
• id/token webhook
• boundBy, boundAt, expiresAt

Trạng thái được lưu trữ trên globalThis để giữ một registry được chia sẻ qua ESM và đường dẫn loader Jiti.

Cấu hình

Thứ tự ưu tiên có hiệu lực

Cho tùy chọn binding thread Discord, ghi đè tài khoản thắng, sau đó kênh, sau đó mặc định phiên toàn cầu, sau đó dự phòng tích hợp.

• tài khoản: channels.discord.accounts.<id>.threadBindings.<key>
• kênh: channels.discord.threadBindings.<key>
• toàn cầu: session.threadBindings.<key>

Key

Hiệu ứng runtime của switch bật

Khi enabled có hiệu lực là false cho tài khoản Discord:

• provider tạo manager binding thread noop cho kết nối runtime
• không có manager thực được đăng ký để lookup bằng id tài khoản
• routing thread bound đến có hiệu lực bị tắt
• ghi đè routing hoàn thành không giải quyết nguồn thread bound
• /focus, /unfocus và hoạt động riêng binding thread báo cáo không có sẵn
• đường dẫn spawn thread: true trả về lỗi có thể hành động từ lớp hook Discord

Luồng và hành vi

Spawn với thread: true

1. Spawn xác thực mode và quyền.
2. Hook subagent_spawning chạy.
3. Extension Discord kiểm tra flag có hiệu lực:
   • binding thread được bật
   • spawnSubagentSessions được bật
4. Extension thử bind tự động và tạo thread.
5. Nếu bind thất bại:
   • spawn trả về lỗi
   • phiên con tạm thời bị xóa
6. Nếu bind thành công:
   • run con bắt đầu
   • run được đăng ký với mode spawn

Focus và unfocus thủ công

• /focus <target>
  • Chỉ Discord
  • giải quyết mục tiêu subagent hoặc phiên
  • bind thread hiện tại hoặc đã tạo sang phiên mục tiêu
• /unfocus
  • Chỉ thread Discord
  • unbind thread hiện tại

Routing đến

• Preflight Discord kiểm tra id thread hiện tại với manager binding thread.
• Nếu bound, routing phiên có hiệu lực sử dụng key phiên mục tiêu bound.
• Nếu không bound, đường dẫn routing bình thường được sử dụng.

Routing đi

• Phân phối phản hồi kiểm tra xem phiên hiện tại có binding thread không.
• Phiên bound phân phối đến thread qua đường dẫn nhận biết webhook.
• Phiên không bound sử dụng phân phối bot bình thường.

Routing hoàn thành

• Luồng hoàn thành cốt lõi gọi subagent_delivery_target.
• Extension Discord trả về nguồn thread bound khi nó có thể giải quyết một.
• Cốt lõi hợp nhất nguồn hook với nguồn requester và phân phối hoàn thành.

Dọn dẹp

Dọn dẹp xảy ra khi:

• hoàn thành
• đường dẫn hoàn thành lỗi hoặc timeout
• đường dẫn kill và terminate
• hết hạn TTL
• probe thread archived hoặc deleted
• /unfocus thủ công

Hành vi dọn dẹp bao gồm unbind và nhắn tin tạm biệt tùy chọn.

Lệnh và UX người dùng

Lưu ý:

• /session ttl hiện là hành vi focused thread Discord.
• Text intro và tạm biệt thread được tạo bởi helper message binding thread.

Xử lý thất bại và an toàn

• Spawn trả về lỗi rõ ràng khi binding thread không thể được chuẩn bị.
• Thất bại spawn sau khi thử bind tạm thời unbind best-effort và xóa phiên.
• Logic hoàn thành ngăn emission hook ended trùng lặp.
• Bảo vệ retry và expiry ngăn vòng lặp retry công bố hoàn thành vô hạn.
• Ngăn chặn echo webhook tránh message webhook không bound được xử lý lại như turn đến.

Bản đồ module

Điều phối cốt lõi

• src/agents/subagent-spawn.ts
• src/agents/subagent-announce.ts
• src/agents/subagent-registry.ts
• src/agents/subagent-registry-cleanup.ts
• src/agents/subagent-registry-completion.ts

Runtime Discord

• src/discord/monitor/provider.ts
• src/discord/monitor/thread-bindings.manager.ts
• src/discord/monitor/thread-bindings.state.ts
• src/discord/monitor/thread-bindings.lifecycle.ts
• src/discord/monitor/thread-bindings.messages.ts
• src/discord/monitor/message-handler.preflight.ts
• src/discord/monitor/message-handler.process.ts
• src/discord/monitor/reply-delivery.ts

Hook plugin và extension

• src/plugins/types.ts
• src/plugins/hooks.ts
• extensions/discord/src/subagent-hooks.ts

Cấu hình và schema

• src/config/types.base.ts
• src/config/types.discord.ts
• src/config/zod-schema.session.ts
• src/config/zod-schema.providers-core.ts
• src/config/schema.help.ts
• src/config/schema.labels.ts

Điểm nổi bật bao phủ test

• extensions/discord/src/subagent-hooks.test.ts
• src/discord/monitor/thread-bindings.ttl.test.ts
• src/discord/monitor/thread-bindings.shared-state.test.ts
• src/discord/monitor/reply-delivery.test.ts
• (và nhiều test khác...)

Tóm tắt hoạt động

• Sử dụng session.threadBindings.enabled như kill switch mặc định toàn cầu.
• Sử dụng channels.discord.threadBindings.enabled và ghi đè tài khoản cho kích hoạt chọn lọc.
• Giữ spawnSubagentSessions tham gia cho hành vi spawn tự động thread.
• Sử dụng cài đặt TTL cho điều khiển chính sách unfocus tự động.

Mô hình này giữ điều phối vòng đời subagent chung trong khi cho Discord một đường dẫn tương tác bound thread đầy đủ.

Kế hoạch liên quan

Cho kiến trúc SessionBinding độc lập kênh và lập kế hoạch iteration phạm vi, xem:

• docs/experiments/plans/session-binding-channel-agnostic.md

ACP vẫn là bước tiếp theo trong kế hoạch đó và cố ý không được triển khai trong luồng bound thread Discord đã cung cấp này.