LLM/moltbot
1
0
Fork 0
mirror of https://github.com/moltbot/moltbot.git synced 2026-03-29 16:54:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: thread-bound subagents on Discord (#21805)

Browse Source 
* docs: thread-bound subagents plan

* docs: add exact thread-bound subagent implementation touchpoints

* Docs: prioritize auto thread-bound subagent flow

* Docs: add ACP harness thread-binding extensions

* Discord: add thread-bound session routing and auto-bind spawn flow

* Subagents: add focus commands and ACP/session binding lifecycle hooks

* Tests: cover thread bindings, focus commands, and ACP unbind hooks

* Docs: add plugin-hook appendix for thread-bound subagents

* Plugins: add subagent lifecycle hook events

* Core: emit subagent lifecycle hooks and decouple Discord bindings

* Discord: handle subagent bind lifecycle via plugin hooks

* Subagents: unify completion finalizer and split registry modules

* Add subagent lifecycle events module

* Hooks: fix subagent ended context key

* Discord: share thread bindings across ESM and Jiti

* Subagents: add persistent sessions_spawn mode for thread-bound sessions

* Subagents: clarify thread intro and persistent completion copy

* test(subagents): stabilize sessions_spawn lifecycle cleanup assertions

* Discord: add thread-bound session TTL with auto-unfocus

* Subagents: fail session spawns when thread bind fails

* Subagents: cover thread session failure cleanup paths

* Session: add thread binding TTL config and /session ttl controls

* Tests: align discord reaction expectations

* Agent: persist sessionFile for keyed subagent sessions

* Discord: normalize imports after conflict resolution

* Sessions: centralize sessionFile resolve/persist helper

* Discord: harden thread-bound subagent session routing

* Rebase: resolve upstream/main conflicts

* Subagents: move thread binding into hooks and split bindings modules

* Docs: add channel-agnostic subagent routing hook plan

* Agents: decouple subagent routing from Discord

* Discord: refactor thread-bound subagent flows

* Subagents: prevent duplicate end hooks and orphaned failed sessions

* Refactor: split subagent command and provider phases

* Subagents: honor hook delivery target overrides

* Discord: add thread binding kill switches and refresh plan doc

* Discord: fix thread bind channel resolution

* Routing: centralize account id normalization

* Discord: clean up thread bindings on startup failures

* Discord: add startup cleanup regression tests

* Docs: add long-term thread-bound subagent architecture

* Docs: split session binding plan and dedupe thread-bound doc

* Subagents: add channel-agnostic session binding routing

* Subagents: stabilize announce completion routing tests

* Subagents: cover multi-bound completion routing

* Subagents: suppress lifecycle hooks on failed thread bind

* tests: fix discord provider mock typing regressions

* docs/protocol: sync slash command aliases and delete param models

* fix: add changelog entry for Discord thread-bound subagents (#21805) (thanks @onutc)

---------

Co-authored-by: Shadow <hi@shadowing.dev>
This commit is contained in:
Onur
2026-02-21 16:14:55 +01:00
committed by GitHub
parent 166068dfbe
commit 8178ea472d
114 changed files with 12214 additions and 1659 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
src/plugins/hooks.ts
View File

@@ -36,6 +36,13 @@ import type {
PluginHookSessionContext,
PluginHookSessionEndEvent,
PluginHookSessionStartEvent,
PluginHookSubagentContext,
PluginHookSubagentDeliveryTargetEvent,
PluginHookSubagentDeliveryTargetResult,
PluginHookSubagentSpawningEvent,
PluginHookSubagentSpawningResult,
PluginHookSubagentEndedEvent,
PluginHookSubagentSpawnedEvent,
PluginHookToolContext,
PluginHookToolResultPersistContext,
PluginHookToolResultPersistEvent,
@@ -76,6 +83,13 @@ export type {
PluginHookSessionContext,
PluginHookSessionStartEvent,
PluginHookSessionEndEvent,
PluginHookSubagentContext,
PluginHookSubagentDeliveryTargetEvent,
PluginHookSubagentDeliveryTargetResult,
PluginHookSubagentSpawningEvent,
PluginHookSubagentSpawningResult,
PluginHookSubagentSpawnedEvent,
PluginHookSubagentEndedEvent,
PluginHookGatewayContext,
PluginHookGatewayStartEvent,
PluginHookGatewayStopEvent,
@@ -132,6 +146,32 @@ export function createHookRunner(registry: PluginRegistry, options: HookRunnerOp
: (next.prependContext ?? acc?.prependContext),
});
const mergeSubagentSpawningResult = (
acc: PluginHookSubagentSpawningResult | undefined,
next: PluginHookSubagentSpawningResult,
): PluginHookSubagentSpawningResult => {
if (acc?.status === "error") {
return acc;
}
if (next.status === "error") {
return next;
}
return {
status: "ok",
threadBindingReady: Boolean(acc?.threadBindingReady || next.threadBindingReady),
};
};
const mergeSubagentDeliveryTargetResult = (
acc: PluginHookSubagentDeliveryTargetResult | undefined,
next: PluginHookSubagentDeliveryTargetResult,
): PluginHookSubagentDeliveryTargetResult => {
if (acc?.origin) {
return acc;
}
return next;
};
/**
* Run a hook that doesn't return a value (fire-and-forget style).
* All handlers are executed in parallel for performance.
@@ -570,6 +610,60 @@ export function createHookRunner(registry: PluginRegistry, options: HookRunnerOp
return runVoidHook("session_end", event, ctx);
}
/**
* Run subagent_spawning hook.
* Runs sequentially so channel plugins can deterministically provision session bindings.
*/
async function runSubagentSpawning(
event: PluginHookSubagentSpawningEvent,
ctx: PluginHookSubagentContext,
): Promise<PluginHookSubagentSpawningResult | undefined> {
return runModifyingHook<"subagent_spawning", PluginHookSubagentSpawningResult>(
"subagent_spawning",
event,
ctx,
mergeSubagentSpawningResult,
);
}
/**
* Run subagent_delivery_target hook.
* Runs sequentially so channel plugins can deterministically resolve routing.
*/
async function runSubagentDeliveryTarget(
event: PluginHookSubagentDeliveryTargetEvent,
ctx: PluginHookSubagentContext,
): Promise<PluginHookSubagentDeliveryTargetResult | undefined> {
return runModifyingHook<"subagent_delivery_target", PluginHookSubagentDeliveryTargetResult>(
"subagent_delivery_target",
event,
ctx,
mergeSubagentDeliveryTargetResult,
);
}
/**
* Run subagent_spawned hook.
* Runs in parallel (fire-and-forget).
*/
async function runSubagentSpawned(
event: PluginHookSubagentSpawnedEvent,
ctx: PluginHookSubagentContext,
): Promise<void> {
return runVoidHook("subagent_spawned", event, ctx);
}
/**
* Run subagent_ended hook.
* Runs in parallel (fire-and-forget).
*/
async function runSubagentEnded(
event: PluginHookSubagentEndedEvent,
ctx: PluginHookSubagentContext,
): Promise<void> {
return runVoidHook("subagent_ended", event, ctx);
}
// =========================================================================
// Gateway Hooks
// =========================================================================
@@ -638,6 +732,10 @@ export function createHookRunner(registry: PluginRegistry, options: HookRunnerOp
// Session hooks
runSessionStart,
runSessionEnd,
runSubagentSpawning,
runSubagentDeliveryTarget,
runSubagentSpawned,
runSubagentEnded,
// Gateway hooks
runGatewayStart,
runGatewayStop,

110
src/plugins/types.ts
View File

@@ -314,6 +314,10 @@ export type PluginHookName =
| "before_message_write"
| "session_start"
| "session_end"
| "subagent_spawning"
| "subagent_delivery_target"
| "subagent_spawned"
| "subagent_ended"
| "gateway_start"
| "gateway_stop";
@@ -547,6 +551,93 @@ export type PluginHookSessionEndEvent = {
durationMs?: number;
};
// Subagent context
export type PluginHookSubagentContext = {
runId?: string;
childSessionKey?: string;
requesterSessionKey?: string;
};
export type PluginHookSubagentTargetKind = "subagent" | "acp";
// subagent_spawning hook
export type PluginHookSubagentSpawningEvent = {
childSessionKey: string;
agentId: string;
label?: string;
mode: "run" | "session";
requester?: {
channel?: string;
accountId?: string;
to?: string;
threadId?: string | number;
};
threadRequested: boolean;
};
export type PluginHookSubagentSpawningResult =
| {
status: "ok";
threadBindingReady?: boolean;
}
| {
status: "error";
error: string;
};
// subagent_delivery_target hook
export type PluginHookSubagentDeliveryTargetEvent = {
childSessionKey: string;
requesterSessionKey: string;
requesterOrigin?: {
channel?: string;
accountId?: string;
to?: string;
threadId?: string | number;
};
childRunId?: string;
spawnMode?: "run" | "session";
expectsCompletionMessage: boolean;
};
export type PluginHookSubagentDeliveryTargetResult = {
origin?: {
channel?: string;
accountId?: string;
to?: string;
threadId?: string | number;
};
};
// subagent_spawned hook
export type PluginHookSubagentSpawnedEvent = {
runId: string;
childSessionKey: string;
agentId: string;
label?: string;
mode: "run" | "session";
requester?: {
channel?: string;
accountId?: string;
to?: string;
threadId?: string | number;
};
threadRequested: boolean;
};
// subagent_ended hook
export type PluginHookSubagentEndedEvent = {
targetSessionKey: string;
targetKind: PluginHookSubagentTargetKind;
reason: string;
sendFarewell?: boolean;
accountId?: string;
runId?: string;
endedAt?: number;
outcome?: "ok" | "error" | "timeout" | "killed" | "reset" | "deleted";
error?: string;
};
// Gateway context
export type PluginHookGatewayContext = {
port?: number;
@@ -633,6 +724,25 @@ export type PluginHookHandlerMap = {
event: PluginHookSessionEndEvent,
ctx: PluginHookSessionContext,
) => Promise<void> | void;
subagent_spawning: (
event: PluginHookSubagentSpawningEvent,
ctx: PluginHookSubagentContext,
) => Promise<PluginHookSubagentSpawningResult | void> | PluginHookSubagentSpawningResult | void;
subagent_delivery_target: (
event: PluginHookSubagentDeliveryTargetEvent,
ctx: PluginHookSubagentContext,
) =>
| Promise<PluginHookSubagentDeliveryTargetResult | void>
| PluginHookSubagentDeliveryTargetResult
| void;
subagent_spawned: (
event: PluginHookSubagentSpawnedEvent,
ctx: PluginHookSubagentContext,
) => Promise<void> | void;
subagent_ended: (
event: PluginHookSubagentEndedEvent,
ctx: PluginHookSubagentContext,
) => Promise<void> | void;
gateway_start: (
event: PluginHookGatewayStartEvent,
ctx: PluginHookGatewayContext,

221
src/plugins/wired-hooks-subagent.test.ts Normal file
View File

@@ -0,0 +1,221 @@
/**
* Test: subagent_spawning, subagent_delivery_target, subagent_spawned & subagent_ended hook wiring
*/
import { describe, expect, it, vi } from "vitest";
import { createHookRunner } from "./hooks.js";
import { createMockPluginRegistry } from "./hooks.test-helpers.js";
describe("subagent hook runner methods", () => {
it("runSubagentSpawning invokes registered subagent_spawning hooks", async () => {
const handler = vi.fn(async () => ({ status: "ok", threadBindingReady: true as const }));
const registry = createMockPluginRegistry([{ hookName: "subagent_spawning", handler }]);
const runner = createHookRunner(registry);
const result = await runner.runSubagentSpawning(
{
childSessionKey: "agent:main:subagent:child",
agentId: "main",
label: "research",
mode: "session",
requester: {
channel: "discord",
accountId: "work",
to: "channel:123",
threadId: "456",
},
threadRequested: true,
},
{
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
},
);
expect(handler).toHaveBeenCalledWith(
{
childSessionKey: "agent:main:subagent:child",
agentId: "main",
label: "research",
mode: "session",
requester: {
channel: "discord",
accountId: "work",
to: "channel:123",
threadId: "456",
},
threadRequested: true,
},
{
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
},
);
expect(result).toMatchObject({ status: "ok", threadBindingReady: true });
});
it("runSubagentSpawned invokes registered subagent_spawned hooks", async () => {
const handler = vi.fn();
const registry = createMockPluginRegistry([{ hookName: "subagent_spawned", handler }]);
const runner = createHookRunner(registry);
await runner.runSubagentSpawned(
{
runId: "run-1",
childSessionKey: "agent:main:subagent:child",
agentId: "main",
label: "research",
mode: "run",
requester: {
channel: "discord",
accountId: "work",
to: "channel:123",
threadId: "456",
},
threadRequested: true,
},
{
runId: "run-1",
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
},
);
expect(handler).toHaveBeenCalledWith(
{
runId: "run-1",
childSessionKey: "agent:main:subagent:child",
agentId: "main",
label: "research",
mode: "run",
requester: {
channel: "discord",
accountId: "work",
to: "channel:123",
threadId: "456",
},
threadRequested: true,
},
{
runId: "run-1",
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
},
);
});
it("runSubagentDeliveryTarget invokes registered subagent_delivery_target hooks", async () => {
const handler = vi.fn(async () => ({
origin: {
channel: "discord" as const,
accountId: "work",
to: "channel:777",
threadId: "777",
},
}));
const registry = createMockPluginRegistry([{ hookName: "subagent_delivery_target", handler }]);
const runner = createHookRunner(registry);
const result = await runner.runSubagentDeliveryTarget(
{
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
requesterOrigin: {
channel: "discord",
accountId: "work",
to: "channel:123",
threadId: "456",
},
childRunId: "run-1",
spawnMode: "session",
expectsCompletionMessage: true,
},
{
runId: "run-1",
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
},
);
expect(handler).toHaveBeenCalledWith(
{
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
requesterOrigin: {
channel: "discord",
accountId: "work",
to: "channel:123",
threadId: "456",
},
childRunId: "run-1",
spawnMode: "session",
expectsCompletionMessage: true,
},
{
runId: "run-1",
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
},
);
expect(result).toEqual({
origin: {
channel: "discord",
accountId: "work",
to: "channel:777",
threadId: "777",
},
});
});
it("runSubagentEnded invokes registered subagent_ended hooks", async () => {
const handler = vi.fn();
const registry = createMockPluginRegistry([{ hookName: "subagent_ended", handler }]);
const runner = createHookRunner(registry);
await runner.runSubagentEnded(
{
targetSessionKey: "agent:main:subagent:child",
targetKind: "subagent",
reason: "subagent-complete",
sendFarewell: true,
accountId: "work",
runId: "run-1",
outcome: "ok",
},
{
runId: "run-1",
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
},
);
expect(handler).toHaveBeenCalledWith(
{
targetSessionKey: "agent:main:subagent:child",
targetKind: "subagent",
reason: "subagent-complete",
sendFarewell: true,
accountId: "work",
runId: "run-1",
outcome: "ok",
},
{
runId: "run-1",
childSessionKey: "agent:main:subagent:child",
requesterSessionKey: "agent:main:main",
},
);
});
it("hasHooks returns true for registered subagent hooks", () => {
const registry = createMockPluginRegistry([
{ hookName: "subagent_spawning", handler: vi.fn() },
{ hookName: "subagent_delivery_target", handler: vi.fn() },
]);
const runner = createHookRunner(registry);
expect(runner.hasHooks("subagent_spawning")).toBe(true);
expect(runner.hasHooks("subagent_delivery_target")).toBe(true);
expect(runner.hasHooks("subagent_spawned")).toBe(false);
expect(runner.hasHooks("subagent_ended")).toBe(false);
});
});