create-walle 0.9.21 → 0.9.23

package/template/wall-e/runtime/tool-executor.js

@@ -0,0 +1,269 @@
+'use strict';
+
+const { RuntimeDecisionHookBus } = require('./decision-hooks');
+const { buildRuntimeToolResultEnvelope } = require('./tool-result-envelope');
+
+class RuntimeToolExecutor {
+  constructor({
+    registry = null,
+    runtimeProfile = null,
+    toolSpecs = null,
+    executeToolCall = null,
+    decisionHooks = null,
+    now = () => new Date().toISOString(),
+    clock = () => Date.now(),
+  } = {}) {
+    this.registry = registry;
+    this.runtimeProfile = runtimeProfile || {};
+    this.toolSpecs = Array.isArray(toolSpecs) ? toolSpecs : null;
+    this.executeToolCall = typeof executeToolCall === 'function' ? executeToolCall : null;
+    this.decisionHooks = decisionHooks || new RuntimeDecisionHookBus();
+    this.now = now;
+    this.clock = clock;
+  }
+
+  async run(toolCalls = [], ctx = {}) {
+    const calls = normalizeToolCalls(toolCalls);
+    const specMap = await this._loadSpecMap(ctx);
+    const results = new Array(calls.length);
+    let batch = [];
+
+    const flush = async () => {
+      if (!batch.length) return;
+      const current = batch;
+      batch = [];
+      await Promise.all(current.map(async (item) => {
+        results[item.index] = await this._executeOne(item.call, item.index, specMap.get(item.call.name), ctx);
+      }));
+    };
+
+    for (let index = 0; index < calls.length; index += 1) {
+      const call = calls[index];
+      const spec = specMap.get(call.name) || normalizeRuntimeToolSpec({ name: call.name });
+      if (isRuntimeToolParallelSafe(spec)) {
+        batch.push({ call, index });
+        continue;
+      }
+      await flush();
+      results[index] = await this._executeOne(call, index, spec, ctx);
+    }
+    await flush();
+    return results;
+  }
+
+  async _executeOne(call, index, rawSpec, ctx = {}) {
+    const spec = normalizeRuntimeToolSpec(rawSpec || { name: call.name });
+    const startedAt = this.clock();
+    let finalCall = { ...call, input: call.input || {} };
+    const hookCtx = this._ctx(ctx);
+    const before = await this.decisionHooks.run('tool.before', {
+      call: finalCall,
+      index,
+      input: finalCall.input,
+      spec,
+    }, hookCtx);
+    if (before.input !== undefined) {
+      finalCall = { ...finalCall, input: before.input };
+    }
+    if (before.denied || before.stop) {
+      const result = {
+        ok: false,
+        denied: before.denied,
+        stopped: before.stop,
+        error: before.reason || 'Tool execution stopped by runtime hook',
+      };
+      return this._row({ call: finalCall, spec, result, error: result.error, startedAt });
+    }
+
+    try {
+      let rawResult = this.executeToolCall
+        ? await this.executeToolCall(finalCall, { ...hookCtx, spec, index })
+        : await this._executeViaRegistry(finalCall, hookCtx);
+      const resultForHook = unwrapToolResult(rawResult);
+      const after = await this.decisionHooks.run('tool.after', {
+        call: finalCall,
+        index,
+        input: finalCall.input,
+        spec,
+        rawResult,
+        result: resultForHook,
+      }, hookCtx);
+      if (after.result !== undefined) {
+        rawResult = replaceUnwrappedToolResult(rawResult, after.result);
+      }
+      const result = unwrapToolResult(rawResult);
+      return this._row({ call: finalCall, spec, rawResult, result, startedAt });
+    } catch (error) {
+      const failed = await this.decisionHooks.run('tool.failed', {
+        call: finalCall,
+        index,
+        input: finalCall.input,
+        spec,
+        error,
+      }, hookCtx);
+      const result = failed.result !== undefined
+        ? failed.result
+        : { ok: false, error: error?.message || String(error) };
+      return this._row({ call: finalCall, spec, result, error, startedAt });
+    }
+  }
+
+  async _executeViaRegistry(call, ctx) {
+    if (!this.registry?.execute) {
+      return { ok: false, invalid: true, error: `Tool registry unavailable for ${call.name}` };
+    }
+    return this.registry.execute(call.name, call.input || {}, ctx);
+  }
+
+  _row({ call, spec, rawResult, result, error = null, startedAt }) {
+    const envelope = buildRuntimeToolResultEnvelope({
+      call,
+      spec,
+      result,
+      error,
+      startedAt,
+      endedAt: this.clock(),
+      now: this.now,
+    });
+    return {
+      call,
+      spec,
+      rawResult: rawResult === undefined ? result : rawResult,
+      result,
+      envelope,
+      ok: envelope.ok,
+    };
+  }
+
+  async _loadSpecMap(ctx = {}) {
+    const specs = [];
+    if (this.toolSpecs) specs.push(...this.toolSpecs);
+    if (this.registry?.getToolSpecs) {
+      try {
+        specs.push(...await this.registry.getToolSpecs(this._ctx(ctx)));
+      } catch {}
+    }
+    const map = new Map();
+    for (const spec of specs) {
+      const normalized = normalizeRuntimeToolSpec(spec);
+      if (normalized.name) map.set(normalized.name, normalized);
+    }
+    return map;
+  }
+
+  _ctx(extra = {}) {
+    return {
+      ...extra,
+      runtimeProfile: this.runtimeProfile.profileId || extra.runtimeProfile,
+      permissionProfile: this.runtimeProfile.permissionProfile || extra.permissionProfile,
+      persistenceProfile: this.runtimeProfile.persistenceProfile || extra.persistenceProfile,
+      outputContract: this.runtimeProfile.outputContract || extra.outputContract,
+      toolsets: extra.toolsets || this.runtimeProfile.toolsets || [],
+      channel: this.runtimeProfile.channel || extra.channel,
+      source: this.runtimeProfile.source || extra.source,
+      agentMode: this.runtimeProfile.agentMode || extra.agentMode,
+      agentKind: this.runtimeProfile.agentKind || extra.agentKind,
+      taskType: this.runtimeProfile.taskType || extra.taskType,
+      sessionId: extra.sessionId || this.runtimeProfile.sessionId,
+      ctmSessionId: extra.ctmSessionId || this.runtimeProfile.ctmSessionId,
+      agentSessionId: extra.agentSessionId || this.runtimeProfile.agentSessionId,
+      chatSessionId: extra.chatSessionId || this.runtimeProfile.chatSessionId,
+      cwd: extra.cwd || this.runtimeProfile.cwd,
+    };
+  }
+}
+
+function normalizeToolCalls(toolCalls = []) {
+  return (toolCalls || []).filter(Boolean).map((call, index) => ({
+    id: String(call.id || call.toolCallId || call.tool_call_id || `tool-${index + 1}`),
+    name: String(call.name || call.tool || ''),
+    input: call.input || call.args || call.arguments || {},
+    original: call,
+  })).filter((call) => call.name);
+}
+
+function normalizeRuntimeToolSpec(spec = {}) {
+  const name = String(spec.name || spec.tool || '');
+  const sideEffect = normalizeSideEffect(spec.sideEffect || spec.side_effect || inferSideEffect(name));
+  const readOnly = Boolean(spec.readOnly ?? spec.read_only ?? sideEffect === 'read');
+  const approval = normalizeApproval(spec.approval || spec.approvalPolicy || spec.approval_policy || (readOnly ? 'never' : 'required'));
+  const supportsParallel = Boolean(spec.supportsParallel ?? spec.supports_parallel ?? (readOnly && approval === 'never'));
+  return {
+    ...spec,
+    name,
+    sideEffect,
+    readOnly,
+    approval,
+    supportsParallel,
+    interruptBehavior: normalizeInterruptBehavior(spec.interruptBehavior || spec.interrupt_behavior || (readOnly ? 'cancel' : 'block')),
+    resultBudgetBytes: Number.isFinite(Number(spec.resultBudgetBytes || spec.result_budget_bytes))
+      ? Number(spec.resultBudgetBytes || spec.result_budget_bytes)
+      : undefined,
+    telemetryPolicy: spec.telemetryPolicy || spec.telemetry_policy || 'safe-summary',
+    renderHint: spec.renderHint || spec.render_hint || (readOnly ? 'collapsed-read' : 'expanded-action'),
+    sandboxProfile: spec.sandboxProfile || spec.sandbox_profile || (sideEffect === 'read' ? 'readonly' : 'workspace'),
+  };
+}
+
+function isRuntimeToolParallelSafe(spec = {}) {
+  const normalized = normalizeRuntimeToolSpec(spec);
+  return normalized.supportsParallel === true
+    && normalized.readOnly === true
+    && normalized.approval === 'never'
+    && normalized.sideEffect === 'read';
+}
+
+function normalizeSideEffect(value) {
+  const normalized = String(value || '').toLowerCase();
+  if (['read', 'write', 'external', 'network', 'process', 'none', 'unknown'].includes(normalized)) return normalized;
+  return 'unknown';
+}
+
+function normalizeApproval(value) {
+  const normalized = String(value || '').toLowerCase();
+  if (['never', 'required', 'profile'].includes(normalized)) return normalized;
+  if (normalized === 'always') return 'required';
+  return 'required';
+}
+
+function normalizeInterruptBehavior(value) {
+  const normalized = String(value || '').toLowerCase();
+  return normalized === 'cancel' ? 'cancel' : 'block';
+}
+
+function inferSideEffect(name = '') {
+  const text = String(name || '').toLowerCase();
+  if (!text) return 'unknown';
+  if (/^(read|list|search|grep|glob|find|lookup|get|fetch|check|ctm_context|ctm_remote_access_status|ctm_session_search|think|load|calendar_list|calendar_events|mail_read|mail_search|mail_messages|slack_search|slack_read_channel|clipboard_read|system_info|session_search|session_load|web_fetch)/.test(text)) return 'read';
+  if (/(write|edit|patch|delete|remove|send|reply|create|update|apply|run_shell|shell|screenshot|browser|start_|stop_)/.test(text)) return 'write';
+  if (/(mcp|skill|slack|gmail|calendar|mail|http|web)/.test(text)) return 'external';
+  return 'unknown';
+}
+
+function unwrapToolResult(rawResult) {
+  if (rawResult && typeof rawResult === 'object' && rawResult.call && Object.prototype.hasOwnProperty.call(rawResult.call, 'result')) {
+    return rawResult.call.result;
+  }
+  if (rawResult && typeof rawResult === 'object' && Object.prototype.hasOwnProperty.call(rawResult, 'result') && Object.keys(rawResult).length <= 4) {
+    return rawResult.result;
+  }
+  return rawResult;
+}
+
+function replaceUnwrappedToolResult(rawResult, result) {
+  if (rawResult && typeof rawResult === 'object' && rawResult.call && Object.prototype.hasOwnProperty.call(rawResult.call, 'result')) {
+    return {
+      ...rawResult,
+      call: { ...rawResult.call, result },
+    };
+  }
+  return result;
+}
+
+module.exports = {
+  RuntimeToolExecutor,
+  inferSideEffect,
+  isRuntimeToolParallelSafe,
+  normalizeRuntimeToolSpec,
+  normalizeToolCalls,
+};

package/template/wall-e/runtime/tool-result-envelope.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+const DEFAULT_RESULT_BUDGET_BYTES = 16 * 1024;
+const DEFAULT_PREVIEW_BYTES = 4 * 1024;
+
+function buildRuntimeToolResultEnvelope({
+  call = {},
+  spec = {},
+  result,
+  error = null,
+  startedAt = 0,
+  endedAt = Date.now(),
+  now = () => new Date().toISOString(),
+  resultBudgetBytes,
+  previewBytes = DEFAULT_PREVIEW_BYTES,
+} = {}) {
+  const rawError = error || result?.error || null;
+  const ok = !rawError && result?.invalid !== true && result?.denied !== true;
+  const budget = Number.isFinite(Number(resultBudgetBytes))
+    ? Number(resultBudgetBytes)
+    : Number(spec.resultBudgetBytes || spec.result_budget_bytes || DEFAULT_RESULT_BUDGET_BYTES);
+  const serialized = serializeResult(result);
+  const bytes = Buffer.byteLength(serialized, 'utf8');
+  const outputPreview = truncateBytes(serialized, previewBytes);
+  const truncated = bytes > budget;
+  const outputForModel = rawError
+    ? { error: safeErrorMessage(rawError), ok: false }
+    : truncated
+      ? {
+          ok,
+          truncated: true,
+          bytes,
+          sha256: sha256(serialized),
+          preview: truncateBytes(serialized, Math.min(previewBytes, budget)),
+        }
+      : result;
+
+  return {
+    version: 1,
+    ok,
+    toolCallId: String(call.id || call.toolCallId || call.tool_call_id || ''),
+    name: String(call.name || call.tool || spec.name || ''),
+    inputPreview: previewValue(call.input || call.args || {}),
+    outputPreview,
+    outputForModel,
+    artifactRefs: extractArtifactRefs(result),
+    summary: summarizeResult(result, rawError),
+    error: rawError ? safeErrorMessage(rawError) : null,
+    telemetry: {
+      durationMs: Math.max(0, Number(endedAt || 0) - Number(startedAt || endedAt || 0)),
+      errorType: rawError ? classifyToolError(rawError, result) : '',
+      outputBytes: bytes,
+      truncated,
+      timestamp: now(),
+    },
+  };
+}
+
+function serializeResult(result) {
+  if (typeof result === 'string') return result;
+  try {
+    return JSON.stringify(result == null ? null : result);
+  } catch {
+    return String(result);
+  }
+}
+
+function previewValue(value, maxBytes = 1024) {
+  return truncateBytes(serializeResult(value), maxBytes);
+}
+
+function truncateBytes(text, maxBytes) {
+  const value = String(text || '');
+  const budget = Math.max(0, Number(maxBytes || 0));
+  if (!budget || Buffer.byteLength(value, 'utf8') <= budget) return value;
+  let out = value.slice(0, budget);
+  while (Buffer.byteLength(out, 'utf8') > budget) out = out.slice(0, -1);
+  return `${out}\n[truncated]`;
+}
+
+function summarizeResult(result, error) {
+  if (error) return `Tool failed: ${safeErrorMessage(error)}`;
+  if (result == null) return 'No result';
+  if (typeof result === 'string') return `${result.length} chars`;
+  if (typeof result !== 'object') return String(typeof result);
+  if (result.summary) return String(result.summary);
+  if (result.ok === true) return 'ok';
+  const keys = Object.keys(result).sort().slice(0, 8);
+  return keys.length ? `object: ${keys.join(', ')}` : 'object';
+}
+
+function extractArtifactRefs(result) {
+  const refs = [];
+  const push = (artifact) => {
+    if (!artifact || typeof artifact !== 'object') return;
+    refs.push({
+      artifactId: artifact.artifactId || artifact.id || '',
+      kind: artifact.kind || artifact.type || '',
+      path: artifact.path || artifact.file_path || '',
+      sha256: artifact.sha256 || '',
+      bytes: artifact.bytes || artifact.size || undefined,
+    });
+  };
+  if (result?.artifact) push(result.artifact);
+  if (Array.isArray(result?.artifacts)) result.artifacts.forEach(push);
+  return refs.filter((ref) => ref.artifactId || ref.path || ref.sha256);
+}
+
+function safeErrorMessage(error) {
+  if (!error) return '';
+  if (typeof error === 'string') return error;
+  return String(error.message || error.error || error.reason || error.name || error);
+}
+
+function classifyToolError(error, result) {
+  if (result?.denied) return 'permission_denied';
+  if (result?.invalid) return 'invalid_tool_call';
+  const text = safeErrorMessage(error).toLowerCase();
+  if (/permission|denied|forbidden/.test(text)) return 'permission_denied';
+  if (/timeout|timed out/.test(text)) return 'timeout';
+  if (/abort|cancel/.test(text)) return 'aborted';
+  if (/not found|missing|required|schema|argument/.test(text)) return 'validation';
+  return error?.name || 'tool_error';
+}
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(String(text || '')).digest('hex');
+}
+
+module.exports = {
+  DEFAULT_RESULT_BUDGET_BYTES,
+  buildRuntimeToolResultEnvelope,
+  classifyToolError,
+  previewValue,
+  truncateBytes,
+};

package/template/wall-e/runtime/transcript-projection.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const REPLAYABLE_PART_TYPES = new Set([
+  'message',
+  'user',
+  'assistant',
+  'text',
+  'reasoning',
+  'tool',
+  'diagnostic',
+  'compaction',
+]);
+
+const DURABLE_NON_REPLAY_PART_TYPES = new Set([
+  'artifact',
+  'prompt_manifest',
+  'snapshot',
+  'step_start',
+  'step_finish',
+  'runtime_thread',
+  'runtime_turn',
+  'runtime_item',
+  'runtime_event',
+  'lane_event',
+]);
+
+function isReplayableRuntimePart(partType) {
+  return REPLAYABLE_PART_TYPES.has(String(partType || ''));
+}
+
+function isDurableRuntimePart(partType) {
+  const type = String(partType || '');
+  return REPLAYABLE_PART_TYPES.has(type) || DURABLE_NON_REPLAY_PART_TYPES.has(type);
+}
+
+function runtimeProjectionFlags(partType) {
+  const type = String(partType || '');
+  return {
+    partType: type,
+    durable: isDurableRuntimePart(type),
+    replayable: isReplayableRuntimePart(type),
+    ctmProjectable: type !== 'progress',
+  };
+}
+
+function attachProjectionFlags(record = {}, partType = record.partType || record.type) {
+  return {
+    ...record,
+    runtimeProjection: runtimeProjectionFlags(partType),
+  };
+}
+
+module.exports = {
+  DURABLE_NON_REPLAY_PART_TYPES,
+  REPLAYABLE_PART_TYPES,
+  attachProjectionFlags,
+  isDurableRuntimePart,
+  isReplayableRuntimePart,
+  runtimeProjectionFlags,
+};

package/template/wall-e/runtime/walle-runtime.js

@@ -0,0 +1,224 @@
+'use strict';
+
+const { resolveAgentRunContext } = require('./agent-run-context');
+const { ToolRegistry } = require('../coding/tool-registry');
+const { RuntimeToolExecutor } = require('./tool-executor');
+
+const PROFILE_DEFAULTS = Object.freeze({
+  chat: Object.freeze({
+    profileId: 'chat',
+    permissionProfile: 'assistant-safe',
+    persistenceProfile: 'chat-ledger',
+    outputContract: 'assistant-reply',
+    toolsets: Object.freeze(['chat', 'memory', 'live', 'local', 'handoff']),
+    capabilities: Object.freeze({
+      memory: true,
+      ctmContext: true,
+      liveSources: true,
+      mcp: true,
+      skills: true,
+      localTools: true,
+      shell: true,
+      fileRead: true,
+      fileWrite: true,
+      browser: true,
+      codingHandoff: true,
+      taskDelegation: false,
+      sideEffects: 'permissioned',
+    }),
+  }),
+  coding: Object.freeze({
+    profileId: 'coding',
+    permissionProfile: 'coding-workspace',
+    persistenceProfile: 'jsonl-transcript',
+    outputContract: 'coding-acceptance',
+    toolsets: Object.freeze(['coding', 'memory', 'mcp', 'skills', 'local']),
+    capabilities: Object.freeze({
+      memory: true,
+      ctmContext: true,
+      liveSources: false,
+      mcp: true,
+      skills: true,
+      localTools: true,
+      shell: true,
+      fileRead: true,
+      fileWrite: true,
+      browser: true,
+      codingHandoff: false,
+      taskDelegation: true,
+      sideEffects: 'workspace',
+    }),
+  }),
+  review: Object.freeze({
+    profileId: 'review',
+    permissionProfile: 'review-readonly',
+    persistenceProfile: 'chat-ledger',
+    outputContract: 'review-findings',
+    toolsets: Object.freeze(['review', 'memory', 'project-read']),
+    capabilities: Object.freeze({
+      memory: true,
+      ctmContext: true,
+      liveSources: false,
+      mcp: false,
+      skills: false,
+      localTools: false,
+      shell: false,
+      fileRead: true,
+      fileWrite: false,
+      browser: false,
+      codingHandoff: false,
+      taskDelegation: false,
+      sideEffects: 'read-only',
+    }),
+  }),
+});
+
+function resolveWallERuntimeProfile(input = {}) {
+  const context = input.context?.version === 1 && input.context?.agentMode
+    ? input.context
+    : resolveAgentRunContext(input);
+  const profileId = normalizeRuntimeProfileId(
+    input.runtimeProfile
+      || input.runtime_profile
+      || input.profileId
+      || input.profile_id
+      || context.agentMode
+  );
+  const defaults = PROFILE_DEFAULTS[profileId] || PROFILE_DEFAULTS.chat;
+  const capabilities = {
+    ...defaults.capabilities,
+    ...(input.capabilities && typeof input.capabilities === 'object' ? input.capabilities : {}),
+  };
+
+  return {
+    version: 1,
+    profileId: defaults.profileId,
+    context,
+    channel: context.channel,
+    source: context.source,
+    agentMode: context.agentMode,
+    agentKind: context.agentKind,
+    taskType: context.taskType,
+    sessionId: context.sessionId,
+    ctmSessionId: context.ctmSessionId,
+    agentSessionId: context.agentSessionId,
+    chatSessionId: context.chatSessionId,
+    cwd: context.cwd,
+    jsonlPath: context.jsonlPath,
+    capabilities,
+    permissionProfile: input.permissionProfile || input.permission_profile || defaults.permissionProfile,
+    persistenceProfile: input.persistenceProfile || input.persistence_profile || defaults.persistenceProfile,
+    outputContract: input.outputContract || input.output_contract || defaults.outputContract,
+    toolsets: Array.isArray(input.toolsets) && input.toolsets.length ? [...input.toolsets] : [...defaults.toolsets],
+    warnings: [...(context.warnings || []), ...profileWarnings(context, defaults, capabilities)],
+  };
+}
+
+function normalizeRuntimeProfileId(value) {
+  const raw = String(value || '').trim().toLowerCase().replace(/_/g, '-');
+  if (!raw) return 'chat';
+  if (raw === 'assistant' || raw === 'walle-chat' || raw === 'wall-e-chat') return 'chat';
+  if (raw === 'code' || raw === 'walle-coding' || raw === 'wall-e-coding') return 'coding';
+  if (raw === 'code-review' || raw === 'reviewer') return 'review';
+  return PROFILE_DEFAULTS[raw] ? raw : 'chat';
+}
+
+function profileWarnings(context, defaults, capabilities) {
+  const warnings = [];
+  if (defaults.profileId === 'review' && capabilities.fileWrite) {
+    warnings.push({
+      code: 'review-profile-write-capability',
+      message: 'Review runtime profile must remain read-only',
+    });
+  }
+  if (defaults.profileId === 'coding' && !context.agentSessionId) {
+    warnings.push({
+      code: 'coding-profile-missing-agent-session-id',
+      message: 'Coding runtime profile should have a durable agent session id',
+    });
+  }
+  return warnings;
+}
+
+function runtimeToolContext(runtimeProfile = {}, extra = {}) {
+  return {
+    ...extra,
+    runtimeProfile: runtimeProfile.profileId || extra.runtimeProfile,
+    permissionProfile: runtimeProfile.permissionProfile || extra.permissionProfile,
+    persistenceProfile: runtimeProfile.persistenceProfile || extra.persistenceProfile,
+    outputContract: runtimeProfile.outputContract || extra.outputContract,
+    toolsets: extra.toolsets || runtimeProfile.toolsets || [],
+    channel: runtimeProfile.channel || extra.channel,
+    source: runtimeProfile.source || extra.source,
+    agentMode: runtimeProfile.agentMode || extra.agentMode,
+    agentKind: runtimeProfile.agentKind || extra.agentKind,
+    taskType: runtimeProfile.taskType || extra.taskType,
+    sessionId: runtimeProfile.sessionId || extra.sessionId,
+    ctmSessionId: runtimeProfile.ctmSessionId || extra.ctmSessionId,
+    agentSessionId: runtimeProfile.agentSessionId || extra.agentSessionId,
+    chatSessionId: runtimeProfile.chatSessionId || extra.chatSessionId,
+    cwd: runtimeProfile.cwd || extra.cwd,
+  };
+}
+
+function createWallEToolRegistry({
+  runtimeProfile = null,
+  builtinTools = [],
+  middleware = null,
+  localTools = null,
+  localToolNames = [],
+  mcpClient = null,
+  skillRunner = null,
+  executeBuiltinTool = null,
+  prepareBuiltinArgs = null,
+  unknownToolHandler = null,
+  specialHandlers = {},
+  ...rest
+} = {}) {
+  const localSet = new Set((localToolNames || []).filter(Boolean));
+  const tools = (builtinTools || []).map((tool) => {
+    if (!tool || !tool.name || typeof tool.execute === 'function') return tool;
+    if (!executeBuiltinTool || localSet.has(tool.name)) return tool;
+    return {
+      ...tool,
+      prepareArgs: typeof prepareBuiltinArgs === 'function'
+        ? (args, ctx) => prepareBuiltinArgs(tool.name, args, ctx)
+        : tool.prepareArgs,
+      execute: (args, ctx) => executeBuiltinTool(tool.name, args, ctx),
+    };
+  });
+
+  return new ToolRegistry({
+    ...rest,
+    builtinTools: tools,
+    middleware,
+    localTools,
+    mcpClient,
+    skillRunner,
+    specialHandlers,
+    unknownToolHandler,
+  });
+}
+
+async function getRuntimeToolDefinitions(registry, runtimeProfile, extra = {}) {
+  if (!registry || typeof registry.getDefinitions !== 'function') return [];
+  return registry.getDefinitions(runtimeToolContext(runtimeProfile, extra));
+}
+
+async function executeRuntimeTool(registry, runtimeProfile, name, args = {}, extra = {}) {
+  if (!registry || typeof registry.execute !== 'function') {
+    return { invalid: true, error: `Tool registry unavailable for ${name}` };
+  }
+  return registry.execute(name, args, runtimeToolContext(runtimeProfile, extra));
+}
+
+module.exports = {
+  PROFILE_DEFAULTS,
+  RuntimeToolExecutor,
+  createWallEToolRegistry,
+  executeRuntimeTool,
+  getRuntimeToolDefinitions,
+  normalizeRuntimeProfileId,
+  resolveWallERuntimeProfile,
+  runtimeToolContext,
+};