@agentscope-ai/agentscope 0.0.2 → 0.0.4

package/src/message/block.ts

@@ -16,32 +16,36 @@ export interface HintBlock {
     id: string;
 }
 
+export type ToolCallState = 'pending' | 'asking' | 'allowed' | 'submitted' | 'finished';
+
 export interface ToolCallBlock {
     type: 'tool_call';
     name: string;
     id: string;
     input: string;
-    awaitUserConfirmation?: boolean;
+    state: ToolCallState;
 }
 
+export type ToolResultState = 'success' | 'error' | 'interrupted' | 'denied' | 'running';
+
 export interface ToolResultBlock {
     type: 'tool_result';
     id: string;
     name: string;
     output: string | (TextBlock | DataBlock)[];
-    state: 'success' | 'error' | 'interrupted' | 'running';
+    state: ToolResultState;
 }
 
 export interface Base64Source {
     type: 'base64';
     data: string;
-    mediaType: string;
+    media_type: string;
 }
 
 export interface URLSource {
     type: 'url';
     url: string;
-    mediaType: string;
+    media_type: string;
 }
 
 export interface DataBlock {

package/src/message/index.ts

@@ -1,9 +1,20 @@
-export { Msg, createMsg, getTextContent, getContentBlocks } from './message';
+export {
+    Msg,
+    createMsg,
+    UserMsg,
+    AssistantMsg,
+    SystemMsg,
+    getTextContent,
+    getContentBlocks,
+    appendEvent,
+} from './message';
 export {
     TextBlock,
     ThinkingBlock,
     ToolCallBlock,
+    ToolCallState,
     ToolResultBlock,
+    ToolResultState,
     ContentBlock,
     Base64Source,
     URLSource,

package/src/message/message.test.ts

@@ -13,7 +13,7 @@ describe('Message', () => {
         ]);
         expect(msg.role).toBe('user');
         expect(msg.metadata).toEqual({});
-        expect(msg.timestamp).toBeDefined();
+        expect(msg.created_at).toBeDefined();
         expect(msg.id).toBeDefined();
         expect(getTextContent(msg)).toBe('Hello, world!');
 
@@ -38,6 +38,7 @@ describe('Message', () => {
                     id: '1',
                     name: 'test',
                     input: "{ query: 'What is AI?' }",
+                    state: 'pending',
                 },
                 {
                     type: 'tool_result',
@@ -64,6 +65,7 @@ describe('Message', () => {
                 id: '1',
                 name: 'test',
                 input: "{ query: 'What is AI?' }",
+                state: 'pending',
             },
         ]);
         expect(getContentBlocks(msg, 'tool_result')).toStrictEqual([

package/src/message/message.ts

@@ -6,7 +6,10 @@ import {
     ToolResultBlock,
     ToolCallBlock,
     DataBlock,
+    Base64Source,
+    URLSource,
 } from './block';
+import { AgentEvent, EventType } from '../event';
 
 /** A chat message exchanged between agents or between an agent and a model. */
 export interface Msg {
@@ -21,7 +24,9 @@ export interface Msg {
     /** Arbitrary key-value metadata attached to the message. */
     metadata: Record<string, JSONSerializableObject>;
     /** ISO-8601 creation timestamp. */
-    timestamp: string;
+    created_at: string;
+    /** ISO-8601 finished timestamp. */
+    finished_at?: string | null;
     /** Usage information for the message, such as token counts. */
     usage?: {
         inputTokens: number;
@@ -30,17 +35,18 @@ export interface Msg {
 }
 
 /**
- * Create a new {@link Msg} object, filling in `id` and `timestamp` when omitted.
- *
+ * Create a new {@link Msg} object, filling in `id` and `created_at` when omitted.
+ * A plain string `content` is automatically wrapped in a single {@link TextBlock}.
  * @param root0
  * @param root0.name
  * @param root0.content
  * @param root0.role
  * @param root0.metadata
  * @param root0.id
- * @param root0.timestamp
+ * @param root0.created_at
+ * @param root0.finished_at
  * @param root0.usage
- * @returns A fully-populated {@link Msg} object.
+ * @returns A Msg object.
  */
 export function createMsg({
     name,
@@ -48,11 +54,99 @@ export function createMsg({
     role,
     metadata = {},
     id = crypto.randomUUID(),
-    timestamp = new Date().toISOString(),
+    created_at = new Date().toISOString(),
+    finished_at,
+    usage,
+}: Omit<Msg, 'id' | 'created_at' | 'metadata' | 'content'> &
+    Partial<Pick<Msg, 'id' | 'created_at' | 'metadata'>> & {
+        content: string | ContentBlock[];
+    }): Msg {
+    const contentBlocks: ContentBlock[] =
+        typeof content === 'string'
+            ? [{ id: crypto.randomUUID(), type: 'text', text: content } as TextBlock]
+            : content;
+    return { id, name, role, content: contentBlocks, metadata, created_at, finished_at, usage };
+}
+
+/**
+ * Create a user {@link Msg}.
+ * @param root0
+ * @param root0.name
+ * @param root0.content
+ * @param root0.metadata
+ * @param root0.id
+ * @param root0.created_at
+ * @returns A Msg object with role 'user'.
+ */
+export function UserMsg({
+    name,
+    content,
+    metadata = {},
+    id = crypto.randomUUID(),
+    created_at = new Date().toISOString(),
+}: {
+    name: string;
+    content: string | ContentBlock[];
+    metadata?: Record<string, JSONSerializableObject>;
+    id?: string;
+    created_at?: string;
+}): Msg {
+    return createMsg({ name, content, role: 'user', metadata, id, created_at });
+}
+
+/**
+ * Create an assistant {@link Msg}.
+ * @param root0
+ * @param root0.name
+ * @param root0.content
+ * @param root0.metadata
+ * @param root0.id
+ * @param root0.created_at
+ * @param root0.usage
+ * @returns A Msg object with role 'assistant'.
+ */
+export function AssistantMsg({
+    name,
+    content,
+    metadata = {},
+    id = crypto.randomUUID(),
+    created_at = new Date().toISOString(),
     usage,
-}: Omit<Msg, 'id' | 'timestamp' | 'metadata'> &
-    Partial<Pick<Msg, 'id' | 'timestamp' | 'metadata'>>): Msg {
-    return { id, name, role, content, metadata, timestamp, usage } as Msg;
+}: {
+    name: string;
+    content: string | ContentBlock[];
+    metadata?: Record<string, JSONSerializableObject>;
+    id?: string;
+    created_at?: string;
+    usage?: Msg['usage'];
+}): Msg {
+    return createMsg({ name, content, role: 'assistant', metadata, id, created_at, usage });
+}
+
+/**
+ * Create a system {@link Msg}.
+ * @param root0
+ * @param root0.name
+ * @param root0.content
+ * @param root0.metadata
+ * @param root0.id
+ * @param root0.created_at
+ * @returns A Msg object with role 'system'.
+ */
+export function SystemMsg({
+    name,
+    content,
+    metadata = {},
+    id = crypto.randomUUID(),
+    created_at = new Date().toISOString(),
+}: {
+    name: string;
+    content: string | ContentBlock[];
+    metadata?: Record<string, JSONSerializableObject>;
+    id?: string;
+    created_at?: string;
+}): Msg {
+    return createMsg({ name, content, role: 'system', metadata, id, created_at });
 }
 
 /**
@@ -67,9 +161,7 @@ export function createMsg({
  */
 export function getTextContent(msg: Msg, separator: string = '\n'): string | null {
     const textBlocks = msg.content.filter(block => block.type === 'text');
-    if (textBlocks.length === 0) {
-        return null;
-    }
+    if (textBlocks.length === 0) return null;
     return textBlocks.map(block => (block as TextBlock).text).join(separator);
 }
 
@@ -82,45 +174,10 @@ export function getTextContent(msg: Msg, separator: string = '\n'): string | nul
  * @returns An array of all {@link ContentBlock} objects.
  */
 export function getContentBlocks(msg: Msg): ContentBlock[];
-/**
- * Return all {@link TextBlock} objects from a message.
- *
- * @param msg - The message to read.
- * @param blockType - `'text'`
- * @returns An array of {@link TextBlock} objects.
- */
 export function getContentBlocks(msg: Msg, blockType: 'text'): TextBlock[];
-/**
- * Return all {@link ThinkingBlock} objects from a message.
- *
- * @param msg - The message to read.
- * @param blockType - `'thinking'`
- * @returns An array of {@link ThinkingBlock} objects.
- */
 export function getContentBlocks(msg: Msg, blockType: 'thinking'): ThinkingBlock[];
-/**
- * Return all {@link DataBlock} objects from a message.
- *
- * @param msg - The message to read.
- * @param blockType - `'video'`
- * @returns An array of {@link DataBlock} objects.
- */
 export function getContentBlocks(msg: Msg, blockType: 'data'): DataBlock[];
-/**
- * Return all {@link ToolCallBlock} objects from a message.
- *
- * @param msg - The message to read.
- * @param blockType - `'tool_call'`
- * @returns An array of {@link ToolCallBlock} objects.
- */
 export function getContentBlocks(msg: Msg, blockType: 'tool_call'): ToolCallBlock[];
-/**
- * Return all {@link ToolResultBlock} objects from a message.
- *
- * @param msg - The message to read.
- * @param blockType - `'tool_result'`
- * @returns An array of {@link ToolResultBlock} objects.
- */
 export function getContentBlocks(msg: Msg, blockType: 'tool_result'): ToolResultBlock[];
 export function getContentBlocks(
     msg: Msg,
@@ -129,3 +186,209 @@ export function getContentBlocks(
     if (!blockType) return msg.content;
     return msg.content.filter(block => block.type === blockType);
 }
+
+/**
+ * Find a content block by type and id within a message.
+ * @param msg
+ * @param blockType
+ * @param blockId
+ * @returns The matching {@link ContentBlock}, or `undefined` if not found.
+ */
+function findBlock(msg: Msg, blockType: string, blockId: string): ContentBlock | undefined {
+    return msg.content.find(block => block.type === blockType && block.id === blockId);
+}
+
+/**
+ * Apply a streaming {@link AgentEvent} to a {@link Msg}, mutating it in place.
+ *
+ * Only `content` and `finished_at` are ever modified. Events whose
+ * `reply_id` does not match `msg.id` are skipped with a warning.
+ * @param msg
+ * @param event
+ * @returns The mutated {@link Msg} object.
+ */
+export function appendEvent(msg: Msg, event: AgentEvent): Msg {
+    if (!('reply_id' in event)) return msg;
+    if (event.reply_id !== msg.id) {
+        console.warn(
+            `Event reply_id "${event.reply_id}" does not match message id "${msg.id}", skipping.`
+        );
+        return msg;
+    }
+
+    switch (event.type) {
+        case EventType.REPLY_END:
+            msg.finished_at = event.created_at;
+            break;
+
+        case EventType.TEXT_BLOCK_START:
+            msg.content.push({ type: 'text', id: event.block_id, text: '' });
+            break;
+
+        case EventType.TEXT_BLOCK_DELTA: {
+            const block = findBlock(msg, 'text', event.block_id);
+            if (!block) {
+                console.warn(`TextBlock "${event.block_id}" not found, skipping.`);
+            } else {
+                (block as TextBlock).text += event.delta;
+            }
+            break;
+        }
+
+        case EventType.TEXT_BLOCK_END:
+            break;
+
+        case EventType.THINKING_BLOCK_START:
+            msg.content.push({ type: 'thinking', id: event.block_id, thinking: '' });
+            break;
+
+        case EventType.THINKING_BLOCK_DELTA: {
+            const block = findBlock(msg, 'thinking', event.block_id);
+            if (!block) {
+                console.warn(`ThinkingBlock "${event.block_id}" not found, skipping.`);
+            } else {
+                (block as ThinkingBlock).thinking += event.delta;
+            }
+            break;
+        }
+
+        case EventType.THINKING_BLOCK_END:
+            break;
+
+        case EventType.DATA_BLOCK_START:
+            msg.content.push({
+                type: 'data',
+                id: event.block_id,
+                source: { type: 'base64', data: '', media_type: event.media_type },
+            });
+            break;
+
+        case EventType.DATA_BLOCK_DELTA: {
+            const block = findBlock(msg, 'data', event.block_id);
+            if (!block) {
+                console.warn(`DataBlock "${event.block_id}" not found, skipping.`);
+            } else {
+                ((block as DataBlock).source as Base64Source).data += event.data;
+            }
+            break;
+        }
+
+        case EventType.DATA_BLOCK_END:
+            break;
+
+        case EventType.TOOL_CALL_START:
+            msg.content.push({
+                type: 'tool_call',
+                id: event.tool_call_id,
+                name: event.tool_call_name,
+                input: '',
+                state: 'pending',
+            });
+            break;
+
+        case EventType.TOOL_CALL_DELTA: {
+            const block = findBlock(msg, 'tool_call', event.tool_call_id);
+            if (!block) {
+                console.warn(`ToolCallBlock "${event.tool_call_id}" not found, skipping.`);
+            } else {
+                (block as ToolCallBlock).input += event.delta;
+            }
+            break;
+        }
+
+        case EventType.TOOL_CALL_END:
+            break;
+
+        case EventType.TOOL_RESULT_START:
+            msg.content.push({
+                type: 'tool_result',
+                id: event.tool_call_id,
+                name: event.tool_call_name,
+                output: [],
+                state: 'running',
+            });
+            break;
+
+        case EventType.TOOL_RESULT_TEXT_DELTA: {
+            const block = findBlock(msg, 'tool_result', event.tool_call_id);
+            if (!block) {
+                console.warn(`ToolResultBlock "${event.tool_call_id}" not found, skipping.`);
+            } else {
+                const trb = block as ToolResultBlock;
+                if (typeof trb.output === 'string') {
+                    trb.output = [{ type: 'text', id: crypto.randomUUID(), text: trb.output }];
+                }
+                const last = trb.output[trb.output.length - 1];
+                if (!last || last.type !== 'text') {
+                    trb.output.push({
+                        type: 'text',
+                        id: event.block_id ?? crypto.randomUUID(),
+                        text: event.delta,
+                    });
+                } else {
+                    (last as TextBlock).text += event.delta;
+                }
+            }
+            break;
+        }
+
+        case EventType.TOOL_RESULT_DATA_DELTA: {
+            const block = findBlock(msg, 'tool_result', event.tool_call_id);
+            if (!block) {
+                console.warn(`ToolResultBlock "${event.tool_call_id}" not found, skipping.`);
+            } else {
+                const trb = block as ToolResultBlock;
+                if (typeof trb.output === 'string') {
+                    trb.output = [{ type: 'text', id: crypto.randomUUID(), text: trb.output }];
+                }
+                const source: Base64Source | URLSource =
+                    event.data != null
+                        ? { type: 'base64', data: event.data, media_type: event.media_type }
+                        : { type: 'url', url: event.url!, media_type: event.media_type };
+                trb.output.push({ type: 'data', id: event.block_id, source });
+            }
+            break;
+        }
+
+        case EventType.TOOL_RESULT_END: {
+            const block = findBlock(msg, 'tool_result', event.tool_call_id);
+            if (!block) {
+                console.warn(`ToolResultBlock "${event.tool_call_id}" not found, skipping.`);
+            } else {
+                (block as ToolResultBlock).state = event.state;
+            }
+            break;
+        }
+
+        case EventType.REQUIRE_USER_CONFIRM:
+            for (const tc of event.tool_calls) {
+                const b = findBlock(msg, 'tool_call', tc.id);
+                if (b) (b as ToolCallBlock).state = 'asking';
+            }
+            break;
+
+        case EventType.USER_CONFIRM_RESULT:
+            for (const result of event.confirm_results) {
+                const b = findBlock(msg, 'tool_call', result.tool_call.id);
+                if (b) {
+                    (b as ToolCallBlock).state = result.confirmed ? 'allowed' : 'finished';
+                }
+            }
+            break;
+
+        case EventType.REQUIRE_EXTERNAL_EXECUTION:
+            for (const tc of event.tool_calls) {
+                const b = findBlock(msg, 'tool_call', tc.id);
+                if (b) (b as ToolCallBlock).state = 'submitted';
+            }
+            break;
+
+        case EventType.EXTERNAL_EXECUTION_RESULT:
+            for (const result of event.execution_results) {
+                msg.content.push(result);
+            }
+            break;
+    }
+
+    return msg;
+}

package/src/model/dashscope-model.test.ts

@@ -122,6 +122,7 @@ describe('DashScopeChatModel', () => {
             name: 'get_current_weather',
             id: 'call-123',
             input: '{"location"',
+            state: 'pending',
         });
 
         // Chunk 4: Tool call with second part of arguments (delta)
@@ -131,6 +132,7 @@ describe('DashScopeChatModel', () => {
             name: 'get_current_weather',
             id: 'call-123',
             input: ':"Beijing"}',
+            state: 'pending',
         });
 
         // Chunk 5: Empty content with usage info
@@ -158,6 +160,7 @@ describe('DashScopeChatModel', () => {
             name: 'get_current_weather',
             id: 'call-123',
             input: '{"location":"Beijing"}',
+            state: 'pending',
         });
 
         // Verify usage
@@ -266,6 +269,7 @@ describe('DashScopeChatModel', () => {
             name: 'get_current_weather',
             id: 'call-123',
             input: '{"location":"Beijing"}',
+            state: 'pending',
         });
 
         // Verify usage

package/src/model/dashscope-model.ts

@@ -231,6 +231,7 @@ export class DashScopeChatModel extends ChatModelBase {
                         id: String(toolCall.id),
                         name: String(toolCall.function.name),
                         input: inputString,
+                        state: 'pending',
                     });
                 }
             });
@@ -354,6 +355,7 @@ export class DashScopeChatModel extends ChatModelBase {
                                 id: meta.id,
                                 name: meta.name,
                                 input: deltaArgs,
+                                state: 'pending',
                             });
                         }
                     });
@@ -387,6 +389,7 @@ export class DashScopeChatModel extends ChatModelBase {
                 id: meta.id,
                 name: meta.name,
                 input: accToolInputs.get(index) || '{}',
+                state: 'pending',
             });
         });
 

package/src/model/deepseek-model.test.ts

@@ -106,6 +106,7 @@ describe('DeepSeekChatModel', () => {
             name: 'get_current_weather',
             id: 'call-123',
             input: '{"location":"Beijing"}',
+            state: 'pending',
         });
 
         // Verify usage
@@ -209,6 +210,7 @@ describe('DeepSeekChatModel', () => {
             name: 'get_current_weather',
             id: 'call-123',
             input: '{"location":"Beijing"}',
+            state: 'pending',
         });
 
         // Verify usage

package/src/model/deepseek-model.ts

@@ -191,6 +191,7 @@ export class DeepSeekChatModel extends ChatModelBase {
                         id: String(toolCall.id),
                         name: String(toolCall.function.name),
                         input: inputString,
+                        state: 'pending',
                     });
                 }
             });
@@ -314,6 +315,7 @@ export class DeepSeekChatModel extends ChatModelBase {
                                 id: meta.id,
                                 name: meta.name,
                                 input: deltaArgs,
+                                state: 'pending',
                             });
                         }
                     });
@@ -347,6 +349,7 @@ export class DeepSeekChatModel extends ChatModelBase {
                 id: meta.id,
                 name: meta.name,
                 input: accToolInputs.get(index) || '{}',
+                state: 'pending',
             });
         });
 

package/src/model/ollama-model.test.ts

@@ -106,6 +106,7 @@ describe('OllamaChatModel', () => {
             type: 'tool_call',
             name: 'get_current_weather',
             input: '{"location":"Beijing"}',
+            state: 'pending',
         });
 
         // Verify usage

package/src/model/ollama-model.ts

@@ -212,6 +212,7 @@ export class OllamaChatModel extends ChatModelBase {
                         id: toolId,
                         name: func.name,
                         input: JSON.stringify(func.arguments),
+                        state: 'pending' as const,
                     };
 
                     toolCalls.set(toolId, toolCallBlock);
@@ -284,6 +285,7 @@ export class OllamaChatModel extends ChatModelBase {
                     id: `${idx}_${toolCall.function.name}`,
                     name: toolCall.function.name,
                     input: JSON.stringify(toolCall.function.arguments),
+                    state: 'pending',
                 });
             }
         }

package/src/model/openai-model.ts

@@ -117,6 +117,7 @@ export class OpenAIChatModel extends ChatModelBase {
                         id: toolCall.id,
                         name: toolCall.function.name,
                         input: toolCall.function.arguments,
+                        state: 'pending',
                     });
                 }
             });
@@ -238,6 +239,7 @@ export class OpenAIChatModel extends ChatModelBase {
                                 id: meta.id,
                                 name: meta.name,
                                 input: deltaArgs,
+                                state: 'pending',
                             });
                         }
                     });
@@ -276,6 +278,7 @@ export class OpenAIChatModel extends ChatModelBase {
                 id: meta.id,
                 name: meta.name,
                 input: accToolInputs.get(index) || '{}',
+                state: 'pending',
             });
         });
 

package/src/permission/index.ts

@@ -0,0 +1,13 @@
+export enum PermissionBehavior {
+    ALLOW = 'allow',
+    DENY = 'deny',
+    ASK = 'ask',
+    PASSTHROUGH = 'passthrough',
+}
+
+export interface PermissionRule {
+    tool_name: string;
+    rule_content: string | null;
+    behavior: PermissionBehavior;
+    source: string;
+}