agent-world 0.13.0 → 0.15.0

package/dist/core/tool-approval.js

@@ -0,0 +1,223 @@
+/**
+ * Tool Approval Module - Shared HITL approval flow for built-in tools.
+ *
+ * Purpose:
+ * - Provide a reusable wrapper around HITL option prompts for tool-level approvals.
+ *
+ * Key Features:
+ * - Standardized approval result contract (`approved`, `reason`, `optionId`, `source`)
+ * - Configurable options/default and multiple approved option IDs
+ * - Deterministic deny/timeout handling for sensitive tool operations
+ * - Optional durable synthetic approval prompt/resolution message persistence
+ *
+ * Implementation Notes:
+ * - Delegates prompt transport/runtime behavior to `requestWorldOption`
+ * - Returns normalized results to reduce duplicated approval mapping logic in tools
+ * - When message context is available, persists canonical approval prompt/resolution artifacts
+ *
+ * Recent Changes:
+ * - 2026-03-12: Added optional durable approval prompt/resolution persistence with separate requestId vs owning toolCallId support.
+ * - 2026-02-28: Initial shared approval helper extracted for `load_skill`, `create_agent`, and `web_fetch`.
+ */
+import { requestWorldOption } from './hitl.js';
+import { createStorageWithWrappers } from './storage/storage-factory.js';
+import { generateId } from './utils.js';
+function normalizeApprovalMessages(messages) {
+    return Array.isArray(messages) ? messages : null;
+}
+function resolveApprovalRequestId(request) {
+    const explicitRequestId = String(request.requestId || '').trim();
+    if (explicitRequestId) {
+        return explicitRequestId;
+    }
+    const explicitToolCallId = String(request.toolCallId || '').trim();
+    if (explicitToolCallId) {
+        return `${explicitToolCallId}::approval`;
+    }
+    const metadataToolCallId = request.metadata && typeof request.metadata.toolCallId === 'string'
+        ? String(request.metadata.toolCallId).trim()
+        : '';
+    if (metadataToolCallId) {
+        return `${metadataToolCallId}::approval`;
+    }
+    return generateId();
+}
+function resolveOwningToolCallId(request, requestId) {
+    const explicitToolCallId = String(request.toolCallId || '').trim();
+    if (explicitToolCallId) {
+        return explicitToolCallId;
+    }
+    const metadataToolCallId = request.metadata && typeof request.metadata.toolCallId === 'string'
+        ? String(request.metadata.toolCallId).trim()
+        : '';
+    if (metadataToolCallId) {
+        return metadataToolCallId;
+    }
+    return requestId;
+}
+function resolveApprovalDefaultOptionLabel(request) {
+    const defaultOptionId = String(request.defaultOptionId || '').trim();
+    if (!defaultOptionId) {
+        return undefined;
+    }
+    const match = request.options.find((option) => String(option?.id || '').trim() === defaultOptionId);
+    const label = String(match?.label || '').trim();
+    return label || undefined;
+}
+function buildApprovalAssistantContent(metadata) {
+    const source = typeof metadata?.source === 'string' ? metadata.source.trim() : '';
+    const skillId = typeof metadata?.skillId === 'string' ? metadata.skillId.trim() : '';
+    if (source === 'load_skill' && skillId) {
+        return `Calling tool: human_intervention_request (skill_id: "${skillId}")`;
+    }
+    return 'Calling tool: human_intervention_request';
+}
+async function persistApprovalAgentMemoryIfAvailable(request) {
+    const messages = normalizeApprovalMessages(request.messages);
+    const worldId = String(request.world?.id || '').trim();
+    const agentName = String(request.agentName || '').trim();
+    const world = request.world;
+    if (!messages || !worldId || !agentName || !world?.agents || typeof world.agents.get !== 'function') {
+        return;
+    }
+    const agent = world.agents.get(agentName);
+    if (!agent) {
+        return;
+    }
+    const storage = await createStorageWithWrappers();
+    await storage.saveAgent(worldId, agent);
+}
+async function persistApprovalPromptMessage(options) {
+    const messages = normalizeApprovalMessages(options.request.messages);
+    if (!messages) {
+        return;
+    }
+    const existingPrompt = messages.some((message) => message?.role === 'assistant'
+        && Array.isArray(message?.tool_calls)
+        && message.tool_calls.some((toolCall) => String(toolCall?.id || '').trim() === options.requestId));
+    if (existingPrompt) {
+        return;
+    }
+    const approvalMetadata = {
+        ...(options.request.metadata && typeof options.request.metadata === 'object' ? options.request.metadata : {}),
+        toolCallId: options.toolCallId,
+    };
+    const promptArguments = {
+        title: options.request.title,
+        question: options.request.message,
+        options: options.request.options.map((option) => ({
+            id: option.id,
+            label: option.label,
+            ...(typeof option.description === 'string' && option.description.trim()
+                ? { description: option.description.trim() }
+                : {}),
+        })),
+        defaultOptionId: options.request.defaultOptionId,
+        ...(resolveApprovalDefaultOptionLabel(options.request)
+            ? { defaultOption: resolveApprovalDefaultOptionLabel(options.request) }
+            : {}),
+        metadata: approvalMetadata,
+    };
+    messages.push({
+        role: 'assistant',
+        content: buildApprovalAssistantContent(options.request.metadata),
+        tool_calls: [{
+                id: options.requestId,
+                type: 'function',
+                function: {
+                    name: 'human_intervention_request',
+                    arguments: JSON.stringify(promptArguments),
+                },
+            }],
+        sender: String(options.request.agentName || '').trim() || 'assistant',
+        createdAt: new Date(),
+        chatId: options.request.chatId,
+        messageId: generateId(),
+        replyToMessageId: options.toolCallId || undefined,
+        agentId: String(options.request.agentName || '').trim() || undefined,
+    });
+    await persistApprovalAgentMemoryIfAvailable(options.request);
+}
+async function persistApprovalResolutionMessage(options) {
+    const messages = normalizeApprovalMessages(options.request.messages);
+    if (!messages) {
+        return;
+    }
+    const existingResolution = messages.some((message) => message?.role === 'tool'
+        && String(message?.tool_call_id || '').trim() === options.requestId);
+    if (existingResolution) {
+        return;
+    }
+    const toolName = options.request.metadata && typeof options.request.metadata.tool === 'string'
+        ? String(options.request.metadata.tool).trim() || null
+        : null;
+    const payload = {
+        requestId: options.requestId,
+        toolCallId: options.toolCallId,
+        tool: toolName,
+        optionId: options.result.optionId,
+        source: options.result.source,
+        reason: options.result.reason,
+        status: options.result.approved
+            ? 'approved'
+            : options.result.reason === 'timeout'
+                ? 'timeout'
+                : 'denied',
+    };
+    messages.push({
+        role: 'tool',
+        content: JSON.stringify(payload),
+        tool_call_id: options.requestId,
+        sender: String(options.request.agentName || '').trim() || 'assistant',
+        createdAt: new Date(),
+        chatId: options.request.chatId,
+        messageId: generateId(),
+        agentId: String(options.request.agentName || '').trim() || undefined,
+    });
+    await persistApprovalAgentMemoryIfAvailable(options.request);
+}
+export async function requestToolApproval(request) {
+    const approvedSet = new Set(request.approvedOptionIds
+        .map((id) => String(id || '').trim())
+        .filter(Boolean));
+    const requestId = resolveApprovalRequestId(request);
+    const toolCallId = resolveOwningToolCallId(request, requestId);
+    await persistApprovalPromptMessage({
+        request,
+        requestId,
+        toolCallId,
+    });
+    const resolution = await requestWorldOption(request.world, {
+        requestId,
+        title: request.title,
+        message: request.message,
+        chatId: request.chatId,
+        defaultOptionId: request.defaultOptionId,
+        options: request.options,
+        metadata: {
+            ...(request.metadata && typeof request.metadata === 'object' ? request.metadata : {}),
+            toolCallId,
+        },
+        agentName: request.agentName ?? null,
+    });
+    const result = approvedSet.has(resolution.optionId)
+        ? {
+            approved: true,
+            reason: 'approved',
+            optionId: resolution.optionId,
+            source: resolution.source,
+        }
+        : {
+            approved: false,
+            reason: resolution.source === 'timeout' ? 'timeout' : 'user_denied',
+            optionId: resolution.optionId,
+            source: resolution.source,
+        };
+    await persistApprovalResolutionMessage({
+        request,
+        requestId,
+        toolCallId,
+        result,
+    });
+    return result;
+}

package/dist/core/tool-approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-approval.js","sourceRoot":"","sources":["../../core/tool-approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,kBAAkB,EAAmB,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA2BxC,SAAS,yBAAyB,CAAC,QAAoC;IACrE,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;AACnD,CAAC;AAED,SAAS,wBAAwB,CAAC,OAA4B;IAC5D,MAAM,iBAAiB,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjE,IAAI,iBAAiB,EAAE,CAAC;QACtB,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,IAAI,kBAAkB,EAAE,CAAC;QACvB,OAAO,GAAG,kBAAkB,YAAY,CAAC;IAC3C,CAAC;IAED,MAAM,kBAAkB,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,OAAO,CAAC,QAAQ,CAAC,UAAU,KAAK,QAAQ;QAC5F,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE;QAC5C,CAAC,CAAC,EAAE,CAAC;IACP,IAAI,kBAAkB,EAAE,CAAC;QACvB,OAAO,GAAG,kBAAkB,YAAY,CAAC;IAC3C,CAAC;IAED,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,uBAAuB,CAAC,OAA4B,EAAE,SAAiB;IAC9E,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,IAAI,kBAAkB,EAAE,CAAC;QACvB,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,MAAM,kBAAkB,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,OAAO,CAAC,QAAQ,CAAC,UAAU,KAAK,QAAQ;QAC5F,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE;QAC5C,CAAC,CAAC,EAAE,CAAC;IACP,IAAI,kBAAkB,EAAE,CAAC;QACvB,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,iCAAiC,CAAC,OAA4B;IACrE,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACrE,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,eAAe,CAAC,CAAC;IACpG,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAChD,OAAO,KAAK,IAAI,SAAS,CAAC;AAC5B,CAAC;AAED,SAAS,6BAA6B,CAAC,QAA6C;IAClF,MAAM,MAAM,GAAG,OAAO,QAAQ,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAClF,MAAM,OAAO,GAAG,OAAO,QAAQ,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACrF,IAAI,MAAM,KAAK,YAAY,IAAI,OAAO,EAAE,CAAC;QACvC,OAAO,wDAAwD,OAAO,IAAI,CAAC;IAC7E,CAAC;IAED,OAAO,0CAA0C,CAAC;AACpD,CAAC;AAED,KAAK,UAAU,qCAAqC,CAAC,OAA4B;IAC/E,MAAM,QAAQ,GAAG,yBAAyB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAY,CAAC;IAEnC,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,MAAM,IAAI,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QACpG,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,yBAAyB,EAAE,CAAC;IAClD,MAAM,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC1C,CAAC;AAED,KAAK,UAAU,4BAA4B,CAAC,OAI3C;IACC,MAAM,QAAQ,GAAG,yBAAyB,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IAED,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAC/C,OAAO,EAAE,IAAI,KAAK,WAAW;WAC1B,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC;WAClC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,QAAa,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,OAAO,CAAC,SAAS,CAAC,CACvG,CAAC;IACF,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO;IACT,CAAC;IAED,MAAM,gBAAgB,GAAG;QACvB,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7G,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC;IACF,MAAM,eAAe,GAAG;QACtB,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK;QAC5B,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO;QACjC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAChD,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,GAAG,CAAC,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ,IAAI,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE;gBACrE,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE;gBAC5C,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;QACH,eAAe,EAAE,OAAO,CAAC,OAAO,CAAC,eAAe;QAChD,GAAG,CAAC,iCAAiC,CAAC,OAAO,CAAC,OAAO,CAAC;YACpD,CAAC,CAAC,EAAE,aAAa,EAAE,iCAAiC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE;YACvE,CAAC,CAAC,EAAE,CAAC;QACP,QAAQ,EAAE,gBAAgB;KAC3B,CAAC;IAEF,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,6BAA6B,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;QAChE,UAAU,EAAE,CAAC;gBACX,EAAE,EAAE,OAAO,CAAC,SAAS;gBACrB,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE;oBACR,IAAI,EAAE,4BAA4B;oBAClC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC;iBAC3C;aACF,CAAC;QACF,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,WAAW;QACrE,SAAS,EAAE,IAAI,IAAI,EAAE;QACrB,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM;QAC9B,SAAS,EAAE,UAAU,EAAE;QACvB,gBAAgB,EAAE,OAAO,CAAC,UAAU,IAAI,SAAS;QACjD,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS;KACrD,CAAC,CAAC;IAEnB,MAAM,qCAAqC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,KAAK,UAAU,gCAAgC,CAAC,OAK/C;IACC,MAAM,QAAQ,GAAG,yBAAyB,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IAED,MAAM,kBAAkB,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CACnD,OAAO,EAAE,IAAI,KAAK,MAAM;WACrB,MAAM,CAAC,OAAO,EAAE,YAAY,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,OAAO,CAAC,SAAS,CACpE,CAAC;IACF,IAAI,kBAAkB,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,QAAQ;QAC5F,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI;QACtD,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,OAAO,GAAG;QACd,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ;QACjC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM;QAC7B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM;QAC7B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ;YAC7B,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS;gBACnC,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,QAAQ;KACf,CAAC;IAEF,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QAChC,YAAY,EAAE,OAAO,CAAC,SAAS;QAC/B,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,WAAW;QACrE,SAAS,EAAE,IAAI,IAAI,EAAE;QACrB,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM;QAC9B,SAAS,EAAE,UAAU,EAAE;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS;KACrD,CAAC,CAAC;IAEnB,MAAM,qCAAqC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAA4B;IACpE,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,OAAO,CAAC,iBAAiB;SACtB,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;SACpC,MAAM,CAAC,OAAO,CAAC,CACnB,CAAC;IAEF,MAAM,SAAS,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,uBAAuB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAE/D,MAAM,4BAA4B,CAAC;QACjC,OAAO;QACP,SAAS;QACT,UAAU;KACX,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,KAAK,EAAE;QACzD,SAAS;QACT,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE;YACR,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YACrF,UAAU;SACX;QACD,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;KACrC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAuB,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC;QACrE,CAAC,CAAC;YACA,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,UAAU;YAClB,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B;QACD,CAAC,CAAC;YACA,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,UAAU,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;YACnE,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC;IAEJ,MAAM,gCAAgC,CAAC;QACrC,OAAO;QACP,SAAS;QACT,UAAU;QACV,MAAM;KACP,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/tool-execution-envelope.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Tool Execution Envelope
+ *
+ * Purpose:
+ * - Define the persisted preview/result split for completed tool executions.
+ *
+ * Key Features:
+ * - Shared core envelope and preview types for adopted tools.
+ * - Parsing and serialization helpers for persisted tool-result records.
+ * - Utility helpers for artifact metadata and LLM-safe result extraction.
+ *
+ * Notes on Implementation:
+ * - `preview` is durable UI/history data.
+ * - `result` is the canonical payload reintroduced into LLM continuation.
+ * - The helpers here stay transport-agnostic and do not depend on SSE state.
+ *
+ * Recent Changes:
+ * - 2026-03-06: Initial envelope contract for `shell_cmd` and `load_skill`.
+ */
+export type ToolPreviewKind = 'text' | 'markdown' | 'artifact' | 'media' | 'graphic' | 'url';
+export type ToolPreviewRenderer = 'text' | 'markdown' | 'image' | 'svg' | 'audio' | 'video' | 'youtube' | 'file';
+export interface ToolArtifactReference {
+    path?: string;
+    url?: string;
+    media_type?: string;
+    bytes?: number;
+    display_name?: string;
+}
+interface ToolPreviewBase {
+    kind: ToolPreviewKind;
+    renderer?: ToolPreviewRenderer;
+    media_type?: string;
+    title?: string;
+}
+export interface ToolTextPreview extends ToolPreviewBase {
+    kind: 'text' | 'markdown';
+    text: string;
+}
+export interface ToolUrlPreview extends ToolPreviewBase {
+    kind: 'url';
+    url: string;
+    text?: string;
+}
+export interface ToolArtifactPreview extends ToolPreviewBase {
+    kind: 'artifact' | 'media' | 'graphic';
+    artifact: ToolArtifactReference;
+    url?: string;
+    text?: string;
+}
+export type ToolPreview = ToolTextPreview | ToolUrlPreview | ToolArtifactPreview;
+export interface ToolExecutionEnvelope<T = unknown> {
+    __type: 'tool_execution_envelope';
+    version: 1;
+    tool: string;
+    tool_call_id?: string;
+    status?: string;
+    preview: ToolPreview | ToolPreview[] | null;
+    result: T;
+}
+export declare function isToolExecutionEnvelope(value: unknown): value is ToolExecutionEnvelope;
+export declare function parseToolExecutionEnvelope(value: unknown): ToolExecutionEnvelope | null;
+export declare function parseToolExecutionEnvelopeContent(content: string): ToolExecutionEnvelope | null;
+export declare function serializeToolExecutionEnvelope(envelope: ToolExecutionEnvelope): string;
+export declare function normalizeToolPreviewItems(preview: ToolExecutionEnvelope['preview']): ToolPreview[];
+export declare function stringifyToolExecutionResult(result: unknown): string;
+export declare function buildToolArtifactPreviewUrl(options: {
+    path: string;
+    worldId?: string | null;
+}): string;
+export declare function getToolEventPreviewPayload(content: string): ToolExecutionEnvelope['preview'] | undefined;
+export declare function guessToolPreviewRenderer(mediaType: string | undefined): ToolPreviewRenderer | undefined;
+export declare function guessMediaTypeFromPath(filePath: string): string | undefined;
+export declare function createTextToolPreview(text: string, options?: {
+    markdown?: boolean;
+    title?: string;
+}): ToolTextPreview;
+export declare function createArtifactToolPreview(options: ToolArtifactReference & {
+    title?: string;
+    url?: string;
+}): ToolArtifactPreview;
+export declare function createUrlToolPreview(url: string, options?: {
+    title?: string;
+    text?: string;
+    media_type?: string;
+    renderer?: ToolPreviewRenderer;
+}): ToolUrlPreview;
+export {};

package/dist/core/tool-execution-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-execution-envelope.d.ts","sourceRoot":"","sources":["../../core/tool-execution-envelope.ts"],"names":[],"mappings":"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"}

package/dist/core/tool-execution-envelope.js

@@ -0,0 +1,168 @@
+/**
+ * Tool Execution Envelope
+ *
+ * Purpose:
+ * - Define the persisted preview/result split for completed tool executions.
+ *
+ * Key Features:
+ * - Shared core envelope and preview types for adopted tools.
+ * - Parsing and serialization helpers for persisted tool-result records.
+ * - Utility helpers for artifact metadata and LLM-safe result extraction.
+ *
+ * Notes on Implementation:
+ * - `preview` is durable UI/history data.
+ * - `result` is the canonical payload reintroduced into LLM continuation.
+ * - The helpers here stay transport-agnostic and do not depend on SSE state.
+ *
+ * Recent Changes:
+ * - 2026-03-06: Initial envelope contract for `shell_cmd` and `load_skill`.
+ */
+import { basename, extname } from 'path';
+export function isToolExecutionEnvelope(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return record.__type === 'tool_execution_envelope'
+        && record.version === 1
+        && typeof record.tool === 'string'
+        && Object.prototype.hasOwnProperty.call(record, 'preview')
+        && Object.prototype.hasOwnProperty.call(record, 'result');
+}
+export function parseToolExecutionEnvelope(value) {
+    return isToolExecutionEnvelope(value) ? value : null;
+}
+export function parseToolExecutionEnvelopeContent(content) {
+    const normalized = String(content || '').trim();
+    if (!normalized) {
+        return null;
+    }
+    try {
+        return parseToolExecutionEnvelope(JSON.parse(normalized));
+    }
+    catch {
+        return null;
+    }
+}
+export function serializeToolExecutionEnvelope(envelope) {
+    return JSON.stringify(envelope);
+}
+export function normalizeToolPreviewItems(preview) {
+    if (!preview) {
+        return [];
+    }
+    return Array.isArray(preview) ? preview : [preview];
+}
+export function stringifyToolExecutionResult(result) {
+    if (typeof result === 'string') {
+        return result;
+    }
+    if (result == null) {
+        return '';
+    }
+    try {
+        return JSON.stringify(result, null, 2);
+    }
+    catch {
+        return String(result);
+    }
+}
+export function buildToolArtifactPreviewUrl(options) {
+    const params = new URLSearchParams();
+    params.set('path', options.path);
+    if (options.worldId) {
+        params.set('worldId', options.worldId);
+    }
+    return `/api/tool-artifact?${params.toString()}`;
+}
+export function getToolEventPreviewPayload(content) {
+    const envelope = parseToolExecutionEnvelopeContent(content);
+    if (!envelope) {
+        return undefined;
+    }
+    if (envelope.preview == null) {
+        return undefined;
+    }
+    return envelope.preview;
+}
+export function guessToolPreviewRenderer(mediaType) {
+    const normalized = String(mediaType || '').trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (normalized === 'image/svg+xml')
+        return 'svg';
+    if (normalized.startsWith('image/'))
+        return 'image';
+    if (normalized.startsWith('audio/'))
+        return 'audio';
+    if (normalized.startsWith('video/'))
+        return 'video';
+    if (normalized === 'text/markdown')
+        return 'markdown';
+    if (normalized.startsWith('text/'))
+        return 'text';
+    return 'file';
+}
+export function guessMediaTypeFromPath(filePath) {
+    const extension = extname(String(filePath || '')).toLowerCase();
+    const mediaTypeByExtension = {
+        '.md': 'text/markdown',
+        '.txt': 'text/plain',
+        '.svg': 'image/svg+xml',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif',
+        '.webp': 'image/webp',
+        '.mp3': 'audio/mpeg',
+        '.wav': 'audio/wav',
+        '.ogg': 'audio/ogg',
+        '.m4a': 'audio/mp4',
+        '.mp4': 'video/mp4',
+        '.webm': 'video/webm',
+        '.mov': 'video/quicktime',
+    };
+    return mediaTypeByExtension[extension];
+}
+export function createTextToolPreview(text, options = {}) {
+    return {
+        kind: options.markdown ? 'markdown' : 'text',
+        renderer: options.markdown ? 'markdown' : 'text',
+        ...(options.title ? { title: options.title } : {}),
+        text: String(text || ''),
+    };
+}
+export function createArtifactToolPreview(options) {
+    const mediaType = options.media_type || guessMediaTypeFromPath(options.path || options.display_name || '');
+    const renderer = guessToolPreviewRenderer(mediaType);
+    const kind = mediaType === 'image/svg+xml'
+        ? 'graphic'
+        : mediaType && (mediaType.startsWith('image/') || mediaType.startsWith('audio/') || mediaType.startsWith('video/'))
+            ? 'media'
+            : 'artifact';
+    return {
+        kind,
+        ...(renderer ? { renderer } : {}),
+        ...(mediaType ? { media_type: mediaType } : {}),
+        ...(options.title ? { title: options.title } : {}),
+        ...(options.url ? { url: options.url } : {}),
+        artifact: {
+            ...(options.path ? { path: options.path } : {}),
+            ...(options.url ? { url: options.url } : {}),
+            ...(mediaType ? { media_type: mediaType } : {}),
+            ...(typeof options.bytes === 'number' ? { bytes: options.bytes } : {}),
+            display_name: options.display_name || basename(String(options.path || options.url || 'artifact')),
+        },
+    };
+}
+export function createUrlToolPreview(url, options = {}) {
+    return {
+        kind: 'url',
+        ...(options.renderer ? { renderer: options.renderer } : {}),
+        ...(options.media_type ? { media_type: options.media_type } : {}),
+        ...(options.title ? { title: options.title } : {}),
+        ...(options.text ? { text: options.text } : {}),
+        url,
+    };
+}

package/dist/core/tool-execution-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-execution-envelope.js","sourceRoot":"","sources":["../../core/tool-execution-envelope.ts"],"names":[],"mappings":"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"}

package/dist/core/tool-utils.d.ts

@@ -16,8 +16,12 @@
  * - Consistent parameter validation for both MCP and built-in tools
  *
  * Recent Changes:
+ * - 2026-03-11: Strip workingDirectory/working_directory from shell_cmd args in normalizeKnownParameterAliases; these are context fields the LLM echoes from the system prompt, not tool parameters.
+ * - 2026-03-11: Emit system error event in wrapToolWithValidation when tool parameter validation fails so errors surface in the UI.
+ * - 2026-03-01: Added backward-compatible normalization for `.includePattern` -> `includePattern` in `list_files` and `grep`.
  * - 2026-02-20: Enforced JSON-schema `additionalProperties: false` by rejecting unknown tool arguments during validation.
- * - 2026-02-20: Added `human_intervention_request` parameter alias normalization for `prompt` -> `question` and snake/kebab-case confirmation/input fields.
+ * - 2026-02-27: Added backward-compat cleanup for removed HITL confirmation args by stripping them before schema validation.
+ * - 2026-02-27: Removed deprecated `human_intervention_request` confirmation argument alias normalization; kept `prompt` -> `question` and `default_option` -> `defaultOption`.
  * - 2026-02-20: Added `create_agent` alias normalization for `auto-reply`/`auto_reply` -> `autoReply` and `next agent` variants -> `nextAgent`.
  * - 2026-02-19: Added parameter alias normalization for `read_file`/`read_files` (`path` -> `filePath`) and `grep` path aliases (`path` -> `directoryPath`) to align with shell-style path handling.
  * - 2026-02-06: Removed legacy manual tool-intervention functionality
@@ -49,9 +53,10 @@ interface FunctionCall {
  * @param world - World context for event publishing
  * @param agent - Agent making the calls
  * @param messageId - Message ID for tracking
+ * @param chatId - Explicit chat scope for tool-error event publication
  * @returns Object with validCalls array and toolResults array for invalid calls
  */
-export declare function filterAndHandleEmptyNamedFunctionCalls(functionCalls: FunctionCall[], world: World, agent: Agent, messageId: string): {
+export declare function filterAndHandleEmptyNamedFunctionCalls(functionCalls: FunctionCall[], world: World, agent: Agent, messageId: string, chatId: string): {
     validCalls: FunctionCall[];
     toolResults: ChatMessage[];
 };

package/dist/core/tool-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-utils.d.ts","sourceRoot":"","sources":["../../core/tool-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AA+GtE;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;GAEG;AACH,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,wBAAgB,sCAAsC,CACpD,aAAa,EAAE,YAAY,EAAE,EAC7B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,GAChB;IAAE,UAAU,EAAE,YAAY,EAAE,CAAC;IAAC,WAAW,EAAE,WAAW,EAAE,CAAA;CAAE,CAwC5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG;IACpF,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,GAAG,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CA0GA;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAyBvE"}
+{"version":3,"file":"tool-utils.d.ts","sourceRoot":"","sources":["../../core/tool-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AAkKtE;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;GAEG;AACH,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;;;GASG;AACH,wBAAgB,sCAAsC,CACpD,aAAa,EAAE,YAAY,EAAE,EAC7B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb;IAAE,UAAU,EAAE,YAAY,EAAE,CAAC;IAAC,WAAW,EAAE,WAAW,EAAE,CAAA;CAAE,CAyC5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG;IACpF,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,GAAG,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CA0GA;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAuCvE"}