@agent-creator/core 0.4.2 → 0.5.0

package/README.md

@@ -22,3 +22,100 @@ await agent.run({ input: 'Run my task', sessionId: 'session-1' });
 ```
 
 `baseUrl`, `apiKey`, and `model` are required. The package does not read environment variables automatically.
+
+## Built-In Modules
+
+`@agent-creator/core` includes lightweight defaults that can be replaced one at a time:
+
+- `InMemoryProvider`: process-local session memory with optional message/session limits and TTL.
+- `BasicGuard` / `DefaultGuard`: configurable max input length, blocklist, and allowlist checks.
+- `DefaultPlanner`: explicit skill routing via `metadata.skill`, single-skill auto routing, and `skill.name:` prefix routing.
+- `ModelSkillPlanner`: optional model-driven skill selection that falls back to normal model responses.
+- `DefaultExecutor`: validates skill I/O, applies optional skill `timeoutMs` and `retry`, and emits progress events.
+- `ConsoleTraceProvider` and `InMemoryTraceProvider`: built-in tracing for development and tests.
+- `HttpWebhookService` / `NoopWebhookService`: optional webhook notifications available from planners and skills.
+
+Skills can declare optional execution metadata:
+
+```ts
+const skill = {
+  name: 'calendar.search',
+  description: 'Search calendar events',
+  inputSchema,
+  outputSchema,
+  permission: 'user_private',
+  timeoutMs: 5000,
+  retry: 1,
+  tags: ['calendar'],
+  async execute(input, context) {
+    return searchCalendar(input, context.userId);
+  },
+};
+```
+
+`metadata.skill` and `metadata.skillInput` are stable default-planner conventions for directly invoking a skill:
+
+```ts
+await agent.run({
+  input: 'Search calendar',
+  metadata: {
+    skill: 'calendar.search',
+    skillInput: { query: 'today' },
+  },
+});
+```
+
+OpenAI-compatible models also support optional generation parameters:
+
+```ts
+createAgent({
+  model: {
+    baseUrl: 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: 'gpt-4o-mini',
+    systemPrompt: 'You are a concise assistant.',
+    temperature: 0.2,
+    maxTokens: 512,
+    responseFormat: 'json_object',
+  },
+});
+```
+
+## Webhook Notifications
+
+Webhook is a runtime service for developer-controlled side effects. Configure the URL in code or environment, then call it from a planner or skill through context:
+
+```ts
+const agent = createAgent({
+  model,
+  webhook: {
+    url: process.env.WEBHOOK_URL ?? '',
+  },
+})
+  .useSkill({
+    name: 'build.run',
+    description: 'Run a build',
+    inputSchema,
+    outputSchema,
+    async execute(input, context) {
+      await context.webhook?.notify({
+        event: 'build.completed',
+        message: `Build completed for ${input.project}`,
+      });
+      return { ok: true };
+    },
+  })
+  .build();
+```
+
+Webhook delivery is best-effort by default: missing URLs, HTTP failures, and network errors do not fail the Agent run. The webhook URL is developer configuration and should not come from model output or user input.
+
+For explicit Agent-triggered notifications, register the optional webhook skill:
+
+```ts
+import { createWebhookSkill } from '@agent-creator/core';
+
+builder.useSkill(createWebhookSkill({
+  url: process.env.WEBHOOK_URL ?? '',
+}));
+```

package/dist/defaults.d.ts

@@ -1,17 +1,45 @@
-import type { AgentContext, AgentOutput, AgentPlan, Executor, ExecutorContext, Guard, MemoryMessage, MemoryProvider, Planner, TraceProvider, TraceRun } from './types.js';
+import type { AgentContext, AgentOutput, AgentPlan, Executor, ExecutorContext, Guard, GuardResult, MemoryMessage, MemoryProvider, ModelProvider, Planner, TraceProvider, TraceRun, TraceEvent } from './types.js';
+export interface InMemoryProviderOptions {
+    maxMessagesPerSession?: number;
+    maxSessions?: number;
+    ttlMs?: number;
+    now?: () => number;
+}
 export declare class InMemoryProvider implements MemoryProvider {
+    private readonly options;
     private readonly sessions;
+    constructor(options?: InMemoryProviderOptions);
     append(sessionId: string, message: MemoryMessage): void;
     get(sessionId: string): MemoryMessage[];
     clear(sessionId?: string): void;
+    pruneExpired(): void;
+    size(): number;
+    private enforceMaxSessions;
+    private now;
+}
+export interface BasicGuardOptions {
+    maxInputLength?: number;
+    blocklist?: Array<string | RegExp>;
+    allowlist?: Array<string | RegExp>;
+}
+export declare class BasicGuard implements Guard {
+    private readonly options;
+    constructor(options?: BasicGuardOptions);
+    check(context: AgentContext): GuardResult;
+}
+export declare class DefaultGuard extends BasicGuard {
 }
-export declare class DefaultGuard implements Guard {
-    check(): {
-        allowed: true;
-    };
+export interface DefaultPlannerOptions {
+    model?: ModelProvider;
+    modelDrivenSkillSelection?: boolean;
 }
 export declare class DefaultPlanner implements Planner {
-    plan(context: AgentContext): AgentPlan;
+    private readonly options;
+    constructor(options?: DefaultPlannerOptions);
+    plan(context: AgentContext): Promise<AgentPlan>;
+}
+export declare class ModelSkillPlanner extends DefaultPlanner {
+    constructor(model: ModelProvider);
 }
 export declare class DefaultExecutor implements Executor {
     execute(plan: AgentPlan, context: ExecutorContext): Promise<AgentOutput>;
@@ -19,3 +47,25 @@ export declare class DefaultExecutor implements Executor {
 export declare class NoopTraceProvider implements TraceProvider {
     start(): TraceRun;
 }
+export declare class ConsoleTraceProvider implements TraceProvider {
+    private readonly logger;
+    constructor(logger?: Pick<Console, 'log' | 'error'>);
+    start(input: {
+        input: string;
+    }, traceId: string): TraceRun;
+}
+export interface StoredTraceRun {
+    traceId: string;
+    input: unknown;
+    events: TraceEvent[];
+    output?: AgentOutput;
+    startedAt: string;
+    endedAt?: string;
+}
+export declare class InMemoryTraceProvider implements TraceProvider {
+    private readonly runs;
+    start(input: unknown, traceId: string): TraceRun;
+    get(traceId: string): StoredTraceRun | undefined;
+    list(): StoredTraceRun[];
+    clear(traceId?: string): void;
+}

package/dist/defaults.js

@@ -1,12 +1,26 @@
 export class InMemoryProvider {
+    options;
     sessions = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
     append(sessionId, message) {
-        const messages = this.sessions.get(sessionId) ?? [];
-        messages.push(message);
-        this.sessions.set(sessionId, messages);
+        this.pruneExpired();
+        const current = this.sessions.get(sessionId)?.messages ?? [];
+        const messages = [...current, message];
+        const maxMessages = this.options.maxMessagesPerSession;
+        const trimmed = maxMessages && maxMessages > 0 ? messages.slice(-maxMessages) : messages;
+        this.sessions.delete(sessionId);
+        this.sessions.set(sessionId, { messages: trimmed, touchedAt: this.now() });
+        this.enforceMaxSessions();
     }
     get(sessionId) {
-        return [...(this.sessions.get(sessionId) ?? [])];
+        this.pruneExpired();
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return [];
+        session.touchedAt = this.now();
+        return [...session.messages];
     }
     clear(sessionId) {
         if (sessionId)
@@ -14,14 +28,62 @@ export class InMemoryProvider {
         else
             this.sessions.clear();
     }
+    pruneExpired() {
+        const ttlMs = this.options.ttlMs;
+        if (!ttlMs || ttlMs <= 0)
+            return;
+        const expiresBefore = this.now() - ttlMs;
+        for (const [sessionId, session] of this.sessions) {
+            if (session.touchedAt < expiresBefore)
+                this.sessions.delete(sessionId);
+        }
+    }
+    size() {
+        this.pruneExpired();
+        return this.sessions.size;
+    }
+    enforceMaxSessions() {
+        const maxSessions = this.options.maxSessions;
+        if (!maxSessions || maxSessions <= 0)
+            return;
+        while (this.sessions.size > maxSessions) {
+            const oldest = this.sessions.keys().next().value;
+            if (!oldest)
+                break;
+            this.sessions.delete(oldest);
+        }
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
 }
-export class DefaultGuard {
-    check() {
+export class BasicGuard {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    check(context) {
+        const input = context.input.input;
+        if (this.options.maxInputLength && input.length > this.options.maxInputLength) {
+            return { allowed: false, reason: `Input exceeds max length of ${this.options.maxInputLength}.` };
+        }
+        if (this.options.allowlist?.length && !matchesAny(input, this.options.allowlist)) {
+            return { allowed: false, reason: 'Input is not allowed by the configured allowlist.' };
+        }
+        if (this.options.blocklist?.length && matchesAny(input, this.options.blocklist)) {
+            return { allowed: false, reason: 'Input was blocked by the configured blocklist.' };
+        }
         return { allowed: true };
     }
 }
+export class DefaultGuard extends BasicGuard {
+}
 export class DefaultPlanner {
-    plan(context) {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async plan(context) {
         const requestedSkill = findRequestedSkill(context);
         if (requestedSkill) {
             return {
@@ -29,12 +91,26 @@ export class DefaultPlanner {
                 steps: [{ type: 'skill', skill: requestedSkill, input: context.input.metadata?.skillInput ?? context.input.input }],
             };
         }
+        if (this.options.modelDrivenSkillSelection && this.options.model && context.availableSkills.length > 0) {
+            const selected = await selectSkillWithModel(this.options.model, context);
+            if (selected) {
+                return {
+                    goal: `Execute ${selected}`,
+                    steps: [{ type: 'skill', skill: selected, input: context.input.metadata?.skillInput ?? context.input.input }],
+                };
+            }
+        }
         return {
             goal: 'Generate a response',
             steps: [{ type: 'model', task: 'generate_response', input: context.input.input }],
         };
     }
 }
+export class ModelSkillPlanner extends DefaultPlanner {
+    constructor(model) {
+        super({ model, modelDrivenSkillSelection: true });
+    }
+}
 export class DefaultExecutor {
     async execute(plan, context) {
         let lastOutput;
@@ -44,28 +120,24 @@ export class DefaultExecutor {
             }
             else if (step.type === 'skill') {
                 await context.trace.append({ type: 'skill.start', data: { name: step.skill } });
-                await context.emitProgress({ type: 'skill.started', message: `开始执行 ${step.skill}`, data: { skill: step.skill } });
-                const data = await context.skills.execute(step.skill, step.input, {
-                    traceId: context.traceId,
-                    sessionId: context.input.sessionId,
-                    userId: context.input.userId,
-                    metadata: context.input.metadata,
-                    emitProgress: context.emitProgress,
-                });
-                await context.emitProgress({ type: 'skill.completed', message: `执行 ${step.skill} 完成.`, data: { skill: step.skill } });
+                await context.emitProgress({ type: 'skill.started', message: `Executing ${step.skill}.`, data: { skill: step.skill } });
+                const skill = context.skills.get(step.skill);
+                const data = await executeSkillWithPolicy(skill, step.input, context);
+                await context.emitProgress({ type: 'skill.completed', message: `Finished ${step.skill}.`, data: { skill: step.skill } });
+                await context.trace.append({ type: 'skill.end', data: { name: step.skill } });
                 lastOutput = {
                     success: true,
                     intent: 'skill',
-                    message: `${step.skill} 调用成功.`,
+                    message: `${step.skill} completed.`,
                     data,
                     traceId: context.traceId,
                 };
             }
             else {
                 const memory = context.input.sessionId ? await context.memory.get(context.input.sessionId) : [];
-                await context.emitProgress({ type: 'model.started', message: '调用大模型分析', data: { task: step.task } });
+                await context.emitProgress({ type: 'model.started', message: 'Calling model.', data: { task: step.task } });
                 const result = await context.model.generate({ task: step.task, input: step.input, memory });
-                await context.emitProgress({ type: 'model.completed', message: '大模型分析完成', data: { task: step.task } });
+                await context.emitProgress({ type: 'model.completed', message: 'Model call completed.', data: { task: step.task } });
                 lastOutput = {
                     success: true,
                     intent: step.task,
@@ -78,7 +150,8 @@ export class DefaultExecutor {
         return lastOutput ?? {
             success: false,
             intent: 'empty_plan',
-            message: '没有可执行的步骤',
+            message: 'No executable plan steps.',
+            errorDetails: [{ code: 'empty_plan', message: 'No executable plan steps.' }],
             traceId: context.traceId,
         };
     }
@@ -91,6 +164,57 @@ export class NoopTraceProvider {
         };
     }
 }
+export class ConsoleTraceProvider {
+    logger;
+    constructor(logger = console) {
+        this.logger = logger;
+    }
+    start(input, traceId) {
+        this.logger.log(`[${traceId}] trace.start`, { input: input.input });
+        return {
+            append: (event) => {
+                this.logger.log(`[${traceId}] ${event.type}`, event.data);
+            },
+            end: (output) => {
+                const log = output.success ? this.logger.log : this.logger.error;
+                log.call(this.logger, `[${traceId}] trace.end`, output);
+            },
+        };
+    }
+}
+export class InMemoryTraceProvider {
+    runs = new Map();
+    start(input, traceId) {
+        const run = {
+            traceId,
+            input,
+            events: [],
+            startedAt: new Date().toISOString(),
+        };
+        this.runs.set(traceId, run);
+        return {
+            append: (event) => {
+                run.events.push({ ...event, at: new Date().toISOString() });
+            },
+            end: (output) => {
+                run.output = output;
+                run.endedAt = new Date().toISOString();
+            },
+        };
+    }
+    get(traceId) {
+        return this.runs.get(traceId);
+    }
+    list() {
+        return [...this.runs.values()];
+    }
+    clear(traceId) {
+        if (traceId)
+            this.runs.delete(traceId);
+        else
+            this.runs.clear();
+    }
+}
 function findRequestedSkill(context) {
     const explicit = context.input.metadata?.skill;
     if (typeof explicit === 'string' && context.availableSkills.some((skill) => skill.name === explicit))
@@ -99,3 +223,84 @@ function findRequestedSkill(context) {
         return context.availableSkills[0]?.name;
     return context.availableSkills.find((skill) => context.input.input.startsWith(`${skill.name}:`))?.name;
 }
+async function selectSkillWithModel(model, context) {
+    const skills = context.availableSkills.map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+    }));
+    const result = await model.generate({
+        task: 'select_skill',
+        input: {
+            instruction: 'Choose the best skill for the user input. Return only a skill name, or "none".',
+            userInput: context.input.input,
+            skills,
+        },
+        memory: context.memory,
+    });
+    const selected = result.text.trim().replace(/^["']|["']$/g, '');
+    if (!selected || selected.toLowerCase() === 'none')
+        return undefined;
+    return context.availableSkills.some((skill) => skill.name === selected) ? selected : undefined;
+}
+async function executeSkillWithPolicy(skill, input, context) {
+    const maxAttempts = Math.max(1, (skill.retry ?? 0) + 1);
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            return await withTimeout(context.skills.execute(skill.name, input, {
+                traceId: context.traceId,
+                sessionId: context.input.sessionId,
+                userId: context.input.userId,
+                metadata: context.input.metadata,
+                webhook: context.webhook,
+                trace: context.trace,
+                emitProgress: context.emitProgress,
+            }), skill.timeoutMs, `skill_timeout: ${skill.name}`);
+        }
+        catch (error) {
+            lastError = error;
+            await context.trace.append({
+                type: 'skill.error',
+                data: { name: skill.name, attempt, error: errorToAgentError(error) },
+            });
+            if (attempt === maxAttempts)
+                break;
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+async function withTimeout(promise, timeoutMs, message) {
+    if (!timeoutMs || timeoutMs <= 0)
+        return promise;
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function matchesAny(input, patterns) {
+    return patterns.some((pattern) => typeof pattern === 'string' ? input.includes(pattern) : pattern.test(input));
+}
+function errorToAgentError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { code: inferErrorCode(message), message };
+}
+function inferErrorCode(message) {
+    if (message.startsWith('skill_timeout'))
+        return 'skill_timeout';
+    if (message.startsWith('skill_not_found'))
+        return 'skill_not_found';
+    if (message.startsWith('skill_input_invalid'))
+        return 'skill_input_invalid';
+    if (message.startsWith('skill_output_invalid'))
+        return 'skill_output_invalid';
+    return 'skill_execution_failed';
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { AgentBuilder, createAgent } from './runtime.js';
-export { DefaultExecutor, DefaultGuard, DefaultPlanner, InMemoryProvider, NoopTraceProvider } from './defaults.js';
+export { BasicGuard, ConsoleTraceProvider, DefaultExecutor, DefaultGuard, DefaultPlanner, InMemoryProvider, InMemoryTraceProvider, ModelSkillPlanner, NoopTraceProvider, } from './defaults.js';
 export { createOpenAICompatibleProvider, normalizeModelConfig } from './openAICompatibleProvider.js';
+export { HttpWebhookService, NoopWebhookService, buildWebhookPayload, createWebhookService, createWebhookSkill, notifyWebhook, sendWebhook, } from './skills/webhook.js';
+export type { WebhookConfig, WebhookDeliveryResult, WebhookEvent, WebhookPayload, WebhookService, } from './skills/webhook.js';
 export { SkillRegistry, ToolRegistry, toolToSkill } from './skillRegistry.js';
-export type { Agent, AgentContext, AgentInput, AgentOutput, AgentPlan, AgentPlanStep, AgentProgressEvent, AgentProgressHandler, CreateAgentOptions, Executor, ExecutorContext, Guard, GuardResult, MemoryMessage, MemoryProvider, ModelGenerateInput, ModelGenerateOutput, ModelProvider, OpenAICompatibleModelConfig, Planner, Skill, SkillContext, SkillRegistryLike, ToolDefinition, ToolRegistryLike, TraceEvent, TraceProvider, TraceRun, } from './types.js';
+export type { Agent, AgentContext, AgentError, AgentErrorCode, AgentInput, AgentOutput, AgentPlan, AgentPlanStep, AgentProgressEvent, AgentProgressHandler, CreateAgentOptions, Executor, ExecutorContext, Guard, GuardResult, MemoryMessage, MemoryProvider, ModelGenerateInput, ModelGenerateOutput, ModelProvider, ModelUsage, OpenAICompatibleModelConfig, Planner, Skill, SkillContext, SkillRegistryLike, ToolDefinition, ToolRegistryLike, TraceEvent, TraceProvider, TraceRun, } from './types.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { AgentBuilder, createAgent } from './runtime.js';
-export { DefaultExecutor, DefaultGuard, DefaultPlanner, InMemoryProvider, NoopTraceProvider } from './defaults.js';
+export { BasicGuard, ConsoleTraceProvider, DefaultExecutor, DefaultGuard, DefaultPlanner, InMemoryProvider, InMemoryTraceProvider, ModelSkillPlanner, NoopTraceProvider, } from './defaults.js';
 export { createOpenAICompatibleProvider, normalizeModelConfig } from './openAICompatibleProvider.js';
+export { HttpWebhookService, NoopWebhookService, buildWebhookPayload, createWebhookService, createWebhookSkill, notifyWebhook, sendWebhook, } from './skills/webhook.js';
 export { SkillRegistry, ToolRegistry, toolToSkill } from './skillRegistry.js';

package/dist/openAICompatibleProvider.d.ts

@@ -3,7 +3,11 @@ export declare const DEFAULT_MODEL = "gpt-4o-mini";
 export interface OpenAICompatibleProviderOptions {
     fetch?: typeof globalThis.fetch;
 }
-export declare function normalizeModelConfig(config: OpenAICompatibleModelConfig): Required<Omit<OpenAICompatibleModelConfig, 'headers'>> & {
+export declare function normalizeModelConfig(config: OpenAICompatibleModelConfig): Required<Omit<OpenAICompatibleModelConfig, 'headers' | 'systemPrompt' | 'temperature' | 'maxTokens' | 'responseFormat'>> & {
     headers: Record<string, string>;
+    systemPrompt?: string;
+    temperature?: number;
+    maxTokens?: number;
+    responseFormat?: 'text' | 'json_object' | Record<string, unknown>;
 };
 export declare function createOpenAICompatibleProvider(modelConfig: OpenAICompatibleModelConfig, options?: OpenAICompatibleProviderOptions): ModelProvider;

package/dist/openAICompatibleProvider.js

@@ -1,5 +1,6 @@
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_RETRIES = 1;
+const DEFAULT_RETRY_BACKOFF_MS = 250;
 export const DEFAULT_MODEL = 'gpt-4o-mini';
 export function normalizeModelConfig(config) {
     const baseUrl = requireValue(config.baseUrl, 'model.baseUrl').replace(/\/+$/, '');
@@ -11,7 +12,12 @@ export function normalizeModelConfig(config) {
         model,
         timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
         maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+        retryBackoffMs: config.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS,
         headers: { ...(config.headers ?? {}) },
+        ...(config.systemPrompt ? { systemPrompt: config.systemPrompt } : {}),
+        ...(config.temperature !== undefined ? { temperature: config.temperature } : {}),
+        ...(config.maxTokens !== undefined ? { maxTokens: config.maxTokens } : {}),
+        ...(config.responseFormat !== undefined ? { responseFormat: config.responseFormat } : {}),
     };
 }
 export function createOpenAICompatibleProvider(modelConfig, options = {}) {
@@ -33,27 +39,36 @@ export function createOpenAICompatibleProvider(modelConfig, options = {}) {
                             authorization: `Bearer ${config.apiKey}`,
                             ...config.headers,
                         },
-                        body: JSON.stringify({
-                            model: config.model,
-                            messages: [
-                                ...input.memory.map((message) => ({ role: message.role, content: message.content })),
-                                { role: 'user', content: stringifyInput(input.input) },
-                            ],
-                        }),
+                        body: JSON.stringify(buildRequestBody(config, input)),
                         signal: controller.signal,
                     });
-                    if (!response.ok)
-                        throw new Error(`model_request_failed: ${response.status} ${await response.text()}`);
+                    if (!response.ok) {
+                        const message = `model_request_failed: ${response.status} ${await response.text()}`;
+                        throw new ModelRequestError(message, response.status, isRetryableStatus(response.status));
+                    }
                     const payload = await response.json();
                     const text = payload.choices?.[0]?.message?.content;
                     if (!text)
                         throw new Error('model_response_invalid: choices[0].message.content is missing');
-                    return { text };
+                    return {
+                        text,
+                        ...(payload.usage ? {
+                            usage: {
+                                promptTokens: payload.usage.prompt_tokens,
+                                completionTokens: payload.usage.completion_tokens,
+                                totalTokens: payload.usage.total_tokens,
+                                raw: payload.usage,
+                            },
+                        } : {}),
+                    };
                 }
                 catch (error) {
                     lastError = error;
                     if (attempt === config.maxRetries)
                         break;
+                    if (!isRetryableError(error))
+                        break;
+                    await sleep(config.retryBackoffMs * 2 ** attempt);
                 }
                 finally {
                     clearTimeout(timer);
@@ -72,3 +87,47 @@ function requireValue(value, field) {
 function stringifyInput(input) {
     return typeof input === 'string' ? input : JSON.stringify(input);
 }
+function buildRequestBody(config, input) {
+    return {
+        model: config.model,
+        messages: [
+            ...(config.systemPrompt ? [{ role: 'system', content: config.systemPrompt }] : []),
+            ...input.memory.map((message) => ({ role: message.role, content: message.content })),
+            { role: 'user', content: stringifyInput(input.input) },
+        ],
+        ...(config.temperature !== undefined ? { temperature: config.temperature } : {}),
+        ...(config.maxTokens !== undefined ? { max_tokens: config.maxTokens } : {}),
+        ...(config.responseFormat !== undefined ? { response_format: normalizeResponseFormat(config.responseFormat) } : {}),
+    };
+}
+function normalizeResponseFormat(responseFormat) {
+    if (responseFormat === 'text')
+        return { type: 'text' };
+    if (responseFormat === 'json_object')
+        return { type: 'json_object' };
+    return responseFormat;
+}
+function isRetryableStatus(status) {
+    return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+function isRetryableError(error) {
+    if (error instanceof ModelRequestError)
+        return error.retryable;
+    if (error instanceof DOMException && error.name === 'AbortError')
+        return true;
+    return !(error instanceof Error) || !error.message.startsWith('model_response_invalid');
+}
+function sleep(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+class ModelRequestError extends Error {
+    status;
+    retryable;
+    constructor(message, status, retryable) {
+        super(message);
+        this.status = status;
+        this.retryable = retryable;
+    }
+}

package/dist/runtime.d.ts

@@ -1,3 +1,4 @@
+import { type WebhookService } from './skills/webhook.js';
 import type { Agent, CreateAgentOptions, Executor, Guard, MemoryProvider, ModelProvider, Planner, Skill, TraceProvider } from './types.js';
 export declare class AgentBuilder {
     private readonly skills;
@@ -7,6 +8,7 @@ export declare class AgentBuilder {
     private model;
     private guard;
     private trace;
+    private webhook;
     constructor(options: CreateAgentOptions);
     useSkill(skill: Skill): this;
     useMemory(memory: MemoryProvider): this;
@@ -15,6 +17,7 @@ export declare class AgentBuilder {
     useModel(model: ModelProvider): this;
     useGuard(guard: Guard): this;
     useTrace(trace: TraceProvider): this;
+    useWebhook(webhook: WebhookService): this;
     build(): Agent;
 }
 export declare function createAgent(options: CreateAgentOptions): AgentBuilder;

package/dist/runtime.js

@@ -1,5 +1,6 @@
 import { DefaultExecutor, DefaultGuard, DefaultPlanner, InMemoryProvider, NoopTraceProvider } from './defaults.js';
 import { createOpenAICompatibleProvider, normalizeModelConfig } from './openAICompatibleProvider.js';
+import { createWebhookService, NoopWebhookService } from './skills/webhook.js';
 import { SkillRegistry, toolToSkill } from './skillRegistry.js';
 export class AgentBuilder {
     skills = new SkillRegistry();
@@ -9,9 +10,11 @@ export class AgentBuilder {
     model;
     guard = new DefaultGuard();
     trace = new NoopTraceProvider();
+    webhook;
     constructor(options) {
         const modelConfig = normalizeModelConfig(options.model);
         this.model = createOpenAICompatibleProvider(modelConfig);
+        this.webhook = options.webhook ? createWebhookService(options.webhook) : new NoopWebhookService();
         for (const tool of options.tools ?? [])
             this.skills.register(toolToSkill(tool));
         for (const tool of options.toolRegistry?.listTools() ?? []) {
@@ -46,6 +49,10 @@ export class AgentBuilder {
         this.trace = trace;
         return this;
     }
+    useWebhook(webhook) {
+        this.webhook = webhook;
+        return this;
+    }
     build() {
         assertFunction(this.memory, 'get', 'memory');
         assertFunction(this.memory, 'append', 'memory');
@@ -54,6 +61,7 @@ export class AgentBuilder {
         assertFunction(this.model, 'generate', 'model');
         assertFunction(this.guard, 'check', 'guard');
         assertFunction(this.trace, 'start', 'trace');
+        assertFunction(this.webhook, 'notify', 'webhook');
         const runtime = {
             skills: this.skills,
             memory: this.memory,
@@ -62,6 +70,7 @@ export class AgentBuilder {
             model: this.model,
             guard: this.guard,
             trace: this.trace,
+            webhook: this.webhook,
         };
         return {
             async run(input) {
@@ -71,20 +80,29 @@ export class AgentBuilder {
                 const traceRun = runtime.trace.start(input, traceId);
                 const progress = progressEmitter(input, traceId);
                 try {
-                    await progress({ type: 'agent.started', message: '智能体开始工作', data: { input: input.input } });
+                    await progress({ type: 'agent.started', message: 'Agent started.', data: { input: input.input } });
                     const memory = input.sessionId ? await runtime.memory.get(input.sessionId) : [];
                     const context = {
                         input,
                         memory,
-                        availableSkills: runtime.skills.list().map(({ name, description }) => ({ name, description })),
+                        availableSkills: runtime.skills.list().map(({ name, description, inputSchema, permission, tags }) => ({
+                            name,
+                            description,
+                            inputSchema,
+                            permission,
+                            tags,
+                        })),
+                        webhook: runtime.webhook,
+                        trace: traceRun,
                     };
-                    await progress({ type: 'guard.started', message: '检查请求防护' });
+                    await progress({ type: 'guard.started', message: 'Checking guard.' });
                     const guardResult = await runtime.guard.check(context);
                     if (!guardResult.allowed) {
                         const output = {
                             success: false,
                             intent: 'safe_redirect',
                             message: guardResult.reason ?? 'The request was blocked by the guard.',
+                            errorDetails: [{ code: 'guard_blocked', message: guardResult.reason ?? 'The request was blocked by the guard.' }],
                             traceId,
                         };
                         await progress({ type: 'guard.blocked', message: output.message });
@@ -92,14 +110,14 @@ export class AgentBuilder {
                         await progress({ type: 'agent.completed', message: 'Agent completed.', data: output });
                         return output;
                     }
-                    await progress({ type: 'guard.completed', message: '请求防护已通过' });
+                    await progress({ type: 'guard.completed', message: 'Guard passed.' });
                     if (input.sessionId) {
                         await runtime.memory.append(input.sessionId, { role: 'user', content: input.input, at: new Date().toISOString() });
                     }
-                    await progress({ type: 'planner.started', message: '正在规划后续步骤' });
+                    await progress({ type: 'planner.started', message: 'Planning next steps.' });
                     const plan = await runtime.planner.plan(context);
                     await traceRun.append({ type: 'plan.created', data: plan });
-                    await progress({ type: 'plan.created', message: '计划已创建', data: plan });
+                    await progress({ type: 'plan.created', message: 'Plan created.', data: plan });
                     const output = await runtime.executor.execute(plan, {
                         input,
                         traceId,
@@ -107,6 +125,7 @@ export class AgentBuilder {
                         model: runtime.model,
                         skills: runtime.skills,
                         trace: traceRun,
+                        webhook: runtime.webhook,
                         emitProgress: progress,
                     });
                     if (input.sessionId) {
@@ -118,17 +137,20 @@ export class AgentBuilder {
                         });
                     }
                     await traceRun.end(output);
-                    await progress({ type: 'agent.completed', message: '智能体工作完成', data: output });
+                    await progress({ type: 'agent.completed', message: 'Agent completed.', data: output });
                     return output;
                 }
                 catch (error) {
+                    const errorDetail = errorToAgentError(error);
                     const output = {
                         success: false,
                         intent: 'runtime_error',
                         message: 'Agent execution failed.',
-                        errors: [error instanceof Error ? error.message : String(error)],
+                        errors: [errorDetail.message],
+                        errorDetails: [errorDetail],
                         traceId,
                     };
+                    await traceRun.append({ type: 'agent.error', data: errorDetail });
                     await traceRun.end(output);
                     await progress({ type: 'agent.failed', message: 'Agent execution failed.', data: output });
                     return output;
@@ -150,6 +172,25 @@ function assertFunction(value, key, moduleName) {
 function createId(prefix) {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
+function errorToAgentError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { code: inferErrorCode(message), message };
+}
+function inferErrorCode(message) {
+    if (message.startsWith('skill_timeout'))
+        return 'skill_timeout';
+    if (message.startsWith('skill_not_found'))
+        return 'skill_not_found';
+    if (message.startsWith('skill_input_invalid'))
+        return 'skill_input_invalid';
+    if (message.startsWith('skill_output_invalid'))
+        return 'skill_output_invalid';
+    if (message.startsWith('model_request_failed'))
+        return 'model_request_failed';
+    if (message.startsWith('model_response_invalid'))
+        return 'model_response_invalid';
+    return 'runtime_error';
+}
 function progressEmitter(input, traceId) {
     const handler = input.metadata?.onProgress;
     return async (event) => {

package/dist/skills/webhook.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import type { Skill, TraceRun } from '../types.js';
+export interface WebhookConfig {
+    url: string;
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+    fetch?: typeof globalThis.fetch;
+    warn?: (message: string) => void;
+}
+export type WebhookEvent = 'build.completed' | 'build.failed' | 'directUpload.completed' | 'directUpload.failed';
+export interface WebhookPayload {
+    event: WebhookEvent;
+    timestamp?: string;
+    message: string;
+    logs?: string[];
+    error?: string;
+}
+export interface WebhookDeliveryResult {
+    delivered: boolean;
+    status?: number;
+    statusText?: string;
+    error?: string;
+}
+export interface WebhookService {
+    notify(payload: WebhookPayload, trace?: TraceRun): Promise<WebhookDeliveryResult>;
+}
+/** 构造 webhook 推送的 payload。 */
+export declare function buildWebhookPayload(params: {
+    event: WebhookEvent;
+    message: string;
+    logs?: string[];
+    error?: string;
+}): WebhookPayload;
+export declare function sendWebhook(url: string, payload: WebhookPayload, timeoutMs?: number, options?: {
+    headers?: Record<string, string>;
+    fetch?: typeof globalThis.fetch;
+    warn?: (message: string) => void;
+}): Promise<WebhookDeliveryResult>;
+export declare function notifyWebhook(config: WebhookConfig | undefined, payload: WebhookPayload): Promise<WebhookDeliveryResult>;
+export declare class NoopWebhookService implements WebhookService {
+    notify(): Promise<WebhookDeliveryResult>;
+}
+export declare class HttpWebhookService implements WebhookService {
+    private readonly config;
+    constructor(config: WebhookConfig);
+    notify(payload: WebhookPayload, trace?: TraceRun): Promise<WebhookDeliveryResult>;
+}
+declare const webhookInputSchema: z.ZodObject<{
+    event: z.ZodEnum<["build.completed", "build.failed", "directUpload.completed", "directUpload.failed"]>;
+    message: z.ZodString;
+    logs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    event: "build.completed" | "build.failed" | "directUpload.completed" | "directUpload.failed";
+    message: string;
+    error?: string | undefined;
+    logs?: string[] | undefined;
+}, {
+    event: "build.completed" | "build.failed" | "directUpload.completed" | "directUpload.failed";
+    message: string;
+    error?: string | undefined;
+    logs?: string[] | undefined;
+}>;
+declare const webhookOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    delivered: z.ZodBoolean;
+    status: z.ZodOptional<z.ZodNumber>;
+    statusText: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    delivered: boolean;
+    ok: boolean;
+    status?: number | undefined;
+    statusText?: string | undefined;
+    error?: string | undefined;
+}, {
+    delivered: boolean;
+    ok: boolean;
+    status?: number | undefined;
+    statusText?: string | undefined;
+    error?: string | undefined;
+}>;
+export declare function createWebhookSkill(configOrService: WebhookConfig | WebhookService): Skill<z.infer<typeof webhookInputSchema>, z.infer<typeof webhookOutputSchema>>;
+export declare function createWebhookService(config?: WebhookConfig): WebhookService;
+export {};

package/dist/skills/webhook.js

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+/** 构造 webhook 推送的 payload。 */
+export function buildWebhookPayload(params) {
+    return {
+        event: params.event,
+        timestamp: new Date().toISOString(),
+        message: params.message,
+        logs: params.logs,
+        error: params.error,
+    };
+}
+export async function sendWebhook(url, payload, timeoutMs = 10_000, options = {}) {
+    if (!url)
+        return { delivered: false };
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        return warnAndReturn(options.warn, 'Global fetch is unavailable. Node.js 18 or newer is required.');
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...(options.headers ?? {}) },
+            body: JSON.stringify(normalizeWebhookPayload(payload)),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const message = `[webhook] delivery failed: HTTP ${response.status} ${response.statusText}`;
+            options.warn?.(message) ?? console.warn(message);
+            return { delivered: false, status: response.status, statusText: response.statusText };
+        }
+        return { delivered: true, status: response.status, statusText: response.statusText };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return warnAndReturn(options.warn, `[webhook] delivery error: ${reason}`, reason);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function notifyWebhook(config, payload) {
+    if (!config?.url)
+        return { delivered: false };
+    return await sendWebhook(config.url, payload, config.timeoutMs, config);
+}
+export class NoopWebhookService {
+    async notify() {
+        return { delivered: false };
+    }
+}
+export class HttpWebhookService {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async notify(payload, trace) {
+        const startedAt = Date.now();
+        const safe = safeWebhookTracePayload(payload);
+        await trace?.append({ type: 'webhook.start', data: safe });
+        const result = await notifyWebhook(this.config, normalizeWebhookPayload(payload));
+        await trace?.append({
+            type: result.delivered ? 'webhook.completed' : 'webhook.failed',
+            data: {
+                ...safe,
+                delivered: result.delivered,
+                status: result.status,
+                statusText: result.statusText,
+                error: result.error,
+                durationMs: Date.now() - startedAt,
+            },
+        });
+        return result;
+    }
+}
+const webhookInputSchema = z.object({
+    event: z.enum(['build.completed', 'build.failed', 'directUpload.completed', 'directUpload.failed']),
+    message: z.string().min(1),
+    logs: z.array(z.string()).optional(),
+    error: z.string().optional(),
+});
+const webhookOutputSchema = z.object({
+    ok: z.boolean(),
+    delivered: z.boolean(),
+    status: z.number().optional(),
+    statusText: z.string().optional(),
+    error: z.string().optional(),
+});
+export function createWebhookSkill(configOrService) {
+    const service = isWebhookService(configOrService) ? configOrService : new HttpWebhookService(configOrService);
+    return {
+        name: 'webhook',
+        description: 'Send a configured webhook notification.',
+        inputSchema: webhookInputSchema,
+        outputSchema: webhookOutputSchema,
+        permission: 'external_api',
+        tags: ['webhook', 'notification'],
+        async execute(input, context) {
+            const result = await service.notify(buildWebhookPayload(input), context.trace);
+            return {
+                ok: true,
+                delivered: result.delivered,
+                status: result.status,
+                statusText: result.statusText,
+                error: result.error,
+            };
+        },
+    };
+}
+export function createWebhookService(config) {
+    return config?.url ? new HttpWebhookService(config) : new NoopWebhookService();
+}
+function normalizeWebhookPayload(payload) {
+    return {
+        ...payload,
+        timestamp: payload.timestamp ?? new Date().toISOString(),
+    };
+}
+function safeWebhookTracePayload(payload) {
+    return {
+        event: payload.event,
+        message: payload.message,
+    };
+}
+function warnAndReturn(warn, message, error) {
+    warn?.(message) ?? console.warn(message);
+    return { delivered: false, error: error ?? message };
+}
+function isWebhookService(value) {
+    return typeof value.notify === 'function';
+}

package/dist/types.d.ts

@@ -1,14 +1,21 @@
 import type { z } from 'zod';
+import type { WebhookConfig, WebhookService } from './skills/webhook.js';
 export interface OpenAICompatibleModelConfig {
     baseUrl: string;
     apiKey: string;
     model?: string;
     timeoutMs?: number;
     maxRetries?: number;
+    retryBackoffMs?: number;
     headers?: Record<string, string>;
+    systemPrompt?: string;
+    temperature?: number;
+    maxTokens?: number;
+    responseFormat?: 'text' | 'json_object' | Record<string, unknown>;
 }
 export interface CreateAgentOptions {
     model: OpenAICompatibleModelConfig;
+    webhook?: WebhookConfig;
     /** @deprecated Register skills with builder.useSkill(). */
     tools?: ToolDefinition[];
     /** @deprecated Register skills with builder.useSkill(). */
@@ -35,13 +42,22 @@ export interface AgentOutput {
     data?: unknown;
     warnings?: string[];
     errors?: string[];
+    errorDetails?: AgentError[];
     traceId?: string;
 }
+export type AgentErrorCode = 'guard_blocked' | 'runtime_error' | 'skill_not_found' | 'skill_input_invalid' | 'skill_output_invalid' | 'skill_timeout' | 'skill_execution_failed' | 'model_request_failed' | 'model_response_invalid' | 'empty_plan';
+export interface AgentError {
+    code: AgentErrorCode | string;
+    message: string;
+    details?: unknown;
+}
 export interface SkillContext {
     traceId: string;
     sessionId?: string;
     userId?: string;
     metadata?: Record<string, unknown>;
+    webhook: WebhookService;
+    trace: TraceRun;
     emitProgress?(event: Omit<AgentProgressEvent, 'traceId' | 'at'>): Promise<void>;
 }
 export interface Skill<I = unknown, O = unknown> {
@@ -49,6 +65,10 @@ export interface Skill<I = unknown, O = unknown> {
     description: string;
     inputSchema: z.ZodType<I>;
     outputSchema: z.ZodType<O>;
+    permission?: 'public' | 'external_api' | 'user_private';
+    timeoutMs?: number;
+    retry?: number;
+    tags?: string[];
     execute(input: I, context: SkillContext): Promise<O>;
 }
 export interface MemoryMessage {
@@ -70,6 +90,13 @@ export interface ModelGenerateInput {
 export interface ModelGenerateOutput {
     text: string;
     data?: unknown;
+    usage?: ModelUsage;
+}
+export interface ModelUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    raw?: unknown;
 }
 export interface ModelProvider {
     generate(input: ModelGenerateInput): Promise<ModelGenerateOutput>;
@@ -77,7 +104,9 @@ export interface ModelProvider {
 export interface AgentContext {
     input: AgentInput;
     memory: MemoryMessage[];
-    availableSkills: ReadonlyArray<Pick<Skill, 'name' | 'description'>>;
+    availableSkills: ReadonlyArray<Pick<Skill, 'name' | 'description' | 'inputSchema' | 'permission' | 'tags'>>;
+    webhook: WebhookService;
+    trace: TraceRun;
 }
 export interface AgentPlan {
     goal: string;
@@ -106,6 +135,7 @@ export interface ExecutorContext {
     model: ModelProvider;
     skills: SkillRegistryLike;
     trace: TraceRun;
+    webhook: WebhookService;
     emitProgress(event: Omit<AgentProgressEvent, 'traceId' | 'at'>): Promise<void>;
 }
 export interface Executor {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-creator/core",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Composable Agent runtime with skills, memory, planning, execution, and OpenAI-compatible models.",
   "type": "module",
   "main": "./dist/index.js",