Skip to content

Commit adb77d7

Browse files
tripolskypetrtripolskypetr
committed
dev-message
1 parent be56c79 commit adb77d7

17 files changed

Lines changed: 486 additions & 6 deletions

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "agent-swarm-kit",
3-
"version": "1.1.135",
3+
"version": "1.1.136",
44
"description": "A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems",
55
"author": {
66
"name": "Petr Tripolsky",

‎src/client/ClientAgent.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1330,6 +1330,38 @@ export class ClientAgent implements IAgent {
13301330
});
13311331
}
13321332

1333+
async commitDeveloperMessage(message: string): Promise<void> {
1334+
GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
1335+
this.params.logger.debug(
1336+
`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} commitDeveloperMessage`,
1337+
{ message }
1338+
);
1339+
this.params.onDeveloperMessage &&
1340+
this.params.onDeveloperMessage(
1341+
this.params.clientId,
1342+
this.params.agentName,
1343+
message
1344+
);
1345+
await this.params.history.push({
1346+
role: "developer",
1347+
agentName: this.params.agentName,
1348+
mode: "tool",
1349+
content: message.trim(),
1350+
});
1351+
await this.params.bus.emit<IBusEvent>(this.params.clientId, {
1352+
type: "commit-developer-message",
1353+
source: "agent-bus",
1354+
input: {
1355+
message,
1356+
},
1357+
output: {},
1358+
context: {
1359+
agentName: this.params.agentName,
1360+
},
1361+
clientId: this.params.clientId,
1362+
});
1363+
}
1364+
13331365
/**
13341366
* Commits a tool request to the agent's history and emits an event via BusService.
13351367
* This method is used to log tool requests and notify the system of the requested tool calls.

‎src/client/ClientOperator.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,19 @@ export class ClientOperator implements IAgent {
194194
return Promise.resolve();
195195
}
196196

197+
/**
198+
* Commits a developer message
199+
* @returns {Promise<void>}
200+
*/
201+
commitDeveloperMessage(message: string): Promise<void> {
202+
GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
203+
this.params.logger.debug(
204+
`ClientOperator agentName=${this.params.agentName} clientId=${this.params.clientId} commitDeveloperMessage - not supported`,
205+
{ message }
206+
);
207+
return Promise.resolve();
208+
}
209+
197210
/**
198211
* Commits tool request (not supported)
199212
* @returns {Promise<string[]>}

‎src/client/ClientSession.ts‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -447,6 +447,39 @@ export class ClientSession implements ISession {
447447
return result;
448448
}
449449

450+
/**
451+
* Commits a developer message to the agent’s history via the swarm’s agent (ClientAgent), logging the action via BusService.
452+
* @param message - The developer message to commit, typically for debugging or internal notes.
453+
* Commits a developer message to the agent’s history via the swarm’s agent (ClientAgent), logging the action via BusService.
454+
* Supports internal debugging or developer notes within the session, enhancing ClientHistory.
455+
* @throws {Error} If committing the message fails.
456+
* @returns
457+
*/
458+
async commitDeveloperMessage(message: string): Promise<void> {
459+
GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
460+
this.params.logger.debug(
461+
`ClientSession clientId=${this.params.clientId} commitDeveloperMessage`,
462+
{
463+
message,
464+
}
465+
);
466+
const agent = await this.params.swarm.getAgent();
467+
const result = await agent.commitDeveloperMessage(message);
468+
await this.params.bus.emit<IBusEvent>(this.params.clientId, {
469+
type: "commit-developer-message",
470+
source: "session-bus",
471+
input: {
472+
message,
473+
},
474+
output: {},
475+
context: {
476+
swarmName: this.params.swarmName,
477+
},
478+
clientId: this.params.clientId,
479+
});
480+
return result;
481+
}
482+
450483
/**
451484
* Commits an assistant message to the agent’s history via the swarm’s agent (ClientAgent) without triggering execution.
452485
* Logs the action via BusService, supporting ClientHistory for assistant response logging.

‎src/client/ClientSwarm.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,20 @@ class NoopAgent implements IAgent {
127127
return await this.defaultAgent.commitSystemMessage(content);
128128
}
129129

130+
/**
131+
* Logs an attempt to commit a developer message for the missing agent and delegates to the default agent's commitDeveloperMessage method.
132+
* @param {string} content - The developer message content to commit.
133+
* @returns {Promise<void>} Resolves when the default agent's commitDeveloperMessage method completes.
134+
* @async
135+
*/
136+
async commitDeveloperMessage(content: string) {
137+
const message = `called commitDeveloperMessage on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
138+
const context = { content };
139+
this.logger.log(message, context);
140+
console.error(message, context);
141+
return await this.defaultAgent.commitDeveloperMessage(content);
142+
}
143+
130144
/**
131145
* Logs an attempt to commit a tool request for the missing agent and delegates to the default agent's commitToolRequest method.
132146
* @param {IToolRequest[]} request - An array of tool requests to commit.

‎src/functions/commit/commitDeveloperMessage.ts‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
import beginContext from "../../utils/beginContext";
2+
import { GLOBAL_CONFIG } from "../../config/params";
3+
import swarm from "../../lib";
4+
5+
/** @private Constant defining the method name for logging and validation context */
6+
const METHOD_NAME = "function.commit.commitDeveloperMessage";
7+
8+
/**
9+
* Function implementation
10+
*/
11+
const commitDeveloperMessageInternal = beginContext(
12+
async (content: string, clientId: string, agentName: string): Promise<void> => {
13+
GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
14+
swarm.loggerService.log(METHOD_NAME, {
15+
content,
16+
clientId,
17+
agentName,
18+
});
19+
20+
swarm.agentValidationService.validate(agentName, METHOD_NAME);
21+
22+
swarm.sessionValidationService.validate(clientId, METHOD_NAME);
23+
const swarmName = swarm.sessionValidationService.getSwarm(clientId);
24+
25+
swarm.swarmValidationService.validate(swarmName, METHOD_NAME);
26+
27+
const currentAgentName = await swarm.swarmPublicService.getAgentName(
28+
METHOD_NAME,
29+
clientId,
30+
swarmName
31+
);
32+
if (currentAgentName !== agentName) {
33+
GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
34+
swarm.loggerService.log(
35+
'function "commitDeveloperMessage" skipped due to the agent change',
36+
{
37+
currentAgentName,
38+
agentName,
39+
clientId,
40+
}
41+
);
42+
return;
43+
}
44+
45+
await swarm.sessionPublicService.commitDeveloperMessage(
46+
content,
47+
METHOD_NAME,
48+
clientId,
49+
swarmName
50+
);
51+
}
52+
);
53+
54+
/**
55+
* Commits a developer-generated message to the active agent in the swarm system.
56+
* Validates the agent, session, and swarm, ensuring the current agent matches the provided agent before committing the message.
57+
* Runs within a beginContext wrapper for execution context management, logging operations via LoggerService.
58+
* Integrates with AgentValidationService (agent validation), SessionValidationService (session and swarm retrieval),
59+
* SwarmValidationService (swarm validation), SwarmPublicService (agent retrieval), SessionPublicService (message committing),
60+
* and LoggerService (logging). Complements functions like commitSystemMessage by handling developer messages
61+
* (e.g., user or developer instructions) rather than system-generated or assistant-generated responses.
62+
*
63+
* @param {string} content - The content of the developer message to commit, typically related to user or developer instructions.
64+
* @param {string} clientId - The ID of the client associated with the session, validated against active sessions.
65+
* @param {string} agentName - The name of the agent to commit the message for, validated against registered agents.
66+
* @returns {Promise<void>} A promise that resolves when the message is committed or skipped (e.g., agent mismatch).
67+
* @throws {Error} If agent, session, or swarm validation fails, propagated from respective validation services.
68+
*/
69+
export async function commitDeveloperMessage(content: string, clientId: string, agentName: string) {
70+
return await commitDeveloperMessageInternal(content, clientId, agentName);
71+
}

‎src/functions/commit/commitDeveloperMessageForce.ts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import beginContext from "../../utils/beginContext";
2+
import { GLOBAL_CONFIG } from "../../config/params";
3+
import swarm from "../../lib";
4+
5+
/** @private Constant defining the method name for logging and validation context */
6+
const METHOD_NAME = "function.commit.commitDeveloperMessageForce";
7+
8+
/**
9+
* Internal implementation for forcefully committing a developer message to a session in the swarm system.
10+
* Logs the operation if enabled, validates the session and swarm, and commits the message via SessionPublicService.
11+
* Skips agent validation and active agent checks, providing a more aggressive commit mechanism.
12+
*
13+
* @param {string} content - The content of the developer message to commit.
14+
* @param {string} clientId - The ID of the client associated with the session.
15+
* @returns {Promise<void>} A promise that resolves when the message is committed.
16+
* @throws {Error} If session or swarm validation fails.
17+
*/
18+
const commitDeveloperMessageForceInternal = beginContext(
19+
async (content: string, clientId: string): Promise<void> => {
20+
GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
21+
swarm.loggerService.log(METHOD_NAME, {
22+
content,
23+
clientId,
24+
});
25+
26+
swarm.sessionValidationService.validate(clientId, METHOD_NAME);
27+
const swarmName = swarm.sessionValidationService.getSwarm(clientId);
28+
29+
swarm.swarmValidationService.validate(swarmName, METHOD_NAME);
30+
31+
await swarm.sessionPublicService.commitDeveloperMessage(
32+
content,
33+
METHOD_NAME,
34+
clientId,
35+
swarmName
36+
);
37+
}
38+
);
39+
40+
/**
41+
* Forcefully commits a developer-generated message to a session in the swarm system, without checking the active agent.
42+
* Validates the session and swarm, then proceeds with committing the message regardless of the current agent state.
43+
* Runs within a beginContext wrapper for execution context management, logging operations via LoggerService.
44+
* Integrates with SessionValidationService (session and swarm retrieval), SwarmValidationService (swarm validation),
45+
* SessionPublicService (message committing), and LoggerService (logging).
46+
* Unlike commitDeveloperMessage, this function skips agent validation and active agent checks, providing a more aggressive commit mechanism,
47+
* analogous to commitAssistantMessageForce vs. commitAssistantMessage.
48+
*
49+
* @param {string} content - The content of the developer message to commit, typically related to developer actions or instructions.
50+
* @param {string} clientId - The ID of the client associated with the session, validated against active sessions.
51+
* @returns {Promise<void>} A promise that resolves when the message is committed.
52+
* @throws {Error} If session or swarm validation fails, propagated from respective validation services.
53+
*/
54+
export async function commitDeveloperMessageForce(content: string, clientId: string) {
55+
return await commitDeveloperMessageForceInternal(content, clientId);
56+
}

‎src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,12 @@ export * from "./functions/other/markOffline";
4545

4646
export * from "./functions/commit/commitToolOutput";
4747
export * from "./functions/commit/commitSystemMessage";
48+
export * from "./functions/commit/commitDeveloperMessage";
4849
export * from "./functions/commit/commitFlush";
4950
export * from "./functions/commit/commitUserMessage";
5051
export * from "./functions/commit/commitToolOutputForce";
5152
export * from "./functions/commit/commitSystemMessageForce";
53+
export * from "./functions/commit/commitDeveloperMessageForce";
5254
export * from "./functions/commit/commitFlushForce";
5355
export * from "./functions/commit/commitUserMessageForce";
5456
export * from "./functions/commit/commitAssistantMessage";

‎src/interfaces/Agent.interface.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -285,6 +285,19 @@ export interface IAgentSchemaInternalCallbacks {
285285
message: string
286286
) => void;
287287

288+
/**
289+
* Optional callback triggered when a developer message is generated.
290+
* @param clientId
291+
* @param agentName
292+
* @param message
293+
* @returns
294+
*/
295+
onDeveloperMessage?: (
296+
clientId: string,
297+
agentName: AgentName,
298+
message: string
299+
) => void;
300+
288301
/**
289302
* Optional callback triggered when a tool request is initiated.
290303
* This callback is used to handle or process tool requests made by the agent.
@@ -564,6 +577,14 @@ export interface IAgent {
564577
*/
565578
commitSystemMessage(message: string): Promise<void>;
566579

580+
/**
581+
* Commits a developer message to the agent's history or state.
582+
* @param {string} message - The developer message content to commit.
583+
* @returns {Promise<void>} A promise that resolves when the message is committed.
584+
* @throws {Error} If committing the message fails.
585+
*/
586+
commitDeveloperMessage(message: string): Promise<void>;
587+
567588
/**
568589
* Commits a user message to the agent's history without triggering a response.
569590
* @param {string} message - The user message content to commit.

0 commit comments

Comments
 (0)