create-walle 0.9.25 → 0.9.26

package/template/claude-task-manager/public/js/tool-state.js

@@ -0,0 +1,155 @@
+// Canonical Wall-E tool-state machine — the SINGLE source of truth for how a
+// tool call's status evolves from the progress events Wall-E streams. Both
+// server-side projections (the per-message transcript `toolCalls` in
+// lib/walle-ctm-history.js AND the WORK-bar lib/runtime-work-registry.js) and
+// the browser (public/js/walle-session.js) consume this one module, so they can
+// never disagree about whether a tool is running, awaiting approval, or done.
+//
+// UMD: `module.exports` under Node (the server libs `require()` it), `window
+// .CTMToolState` in the browser (index.html loads it before walle-session.js).
+//
+// Status set (the machine):
+//   pending              tool announced, not yet executing/approved
+//   awaiting_permission  blocked on the user's approval (NOT "running")
+//   running              actively executing
+//   completed            finished OK
+//   error                failed, denied, or gateway-blocked
+//
+// Transitions (driven by the actual events emitWalleProgress relays):
+//   tool_call            -> running   (unless already awaiting_permission)
+//   permission_request   -> awaiting_permission
+//   permission_resolved  -> running (allow) | error (deny)
+//   tool_result/tool_done-> completed | error (on failure/blocked)
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.CTMToolState = factory();
+})(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  var STATUS = {
+    PENDING: 'pending',
+    AWAITING_PERMISSION: 'awaiting_permission',
+    RUNNING: 'running',
+    COMPLETED: 'completed',
+    ERROR: 'error',
+  };
+
+  var ACTIVE = { pending: true, awaiting_permission: true, running: true };
+  var TERMINAL = { completed: true, error: true };
+
+  // The five tool-lifecycle event types this machine reacts to. Everything else
+  // (thinking, skill_loaded, cancelled, …) is NOT part of a single tool's state
+  // and is left to each projection to handle.
+  var LIFECYCLE = {
+    tool_call: true,
+    permission_request: true,
+    permission_resolved: true,
+    tool_result: true,
+    tool_done: true,
+  };
+
+  function isLifecycleEvent(event) {
+    return !!(event && LIFECYCLE[String(event.type || '')]);
+  }
+
+  // Canonical id extraction — superset of every variant the two server files and
+  // the client used independently.
+  function toolEventId(event) {
+    if (!event) return '';
+    return String(event.id || event.toolCallId || event.tool_call_id || event.callId || event.call_id || '');
+  }
+
+  // Canonical name — returns '' when the event carries no name yet (a bare
+  // id-only block open). Callers decide what to do with the empty case (the
+  // phantom-'tool' kill skips creating anything until a named event arrives).
+  function toolEventName(event) {
+    if (!event) return '';
+    return String(event.tool || event.name || event.toolName || event.tool_name || event.skill || '');
+  }
+
+  function isFailureResult(event) {
+    if (!event) return false;
+    if (event.error || event.failed) return true;
+    if (String(event.status || '').toLowerCase() === 'error') return true;
+    // The stream processor emits a `Blocked <tool>` / `Failed <tool>` summary for
+    // gateway-blocked and errored tools.
+    return /^(Blocked|Failed)\b/i.test(String(event.summary || ''));
+  }
+
+  function isAllowDecision(event) {
+    return String(event && event.decision || '').toLowerCase() === 'allow';
+  }
+
+  // The core transition. Given the PREVIOUS canonical status (or '' if new) and a
+  // raw event, return the next canonical status — or null if the event is not a
+  // tool-lifecycle event (caller should ignore it for tool-state purposes).
+  function nextStatus(prevStatus, event) {
+    if (!isLifecycleEvent(event)) return null;
+    switch (String(event.type)) {
+      case 'tool_call':
+        // A tool that's already waiting on approval stays waiting until resolved.
+        return prevStatus === STATUS.AWAITING_PERMISSION ? STATUS.AWAITING_PERMISSION : STATUS.RUNNING;
+      case 'permission_request':
+        return STATUS.AWAITING_PERMISSION;
+      case 'permission_resolved':
+        return isAllowDecision(event) ? STATUS.RUNNING : STATUS.ERROR;
+      case 'tool_result':
+      case 'tool_done':
+        return isFailureResult(event) ? STATUS.ERROR : STATUS.COMPLETED;
+      default:
+        return null;
+    }
+  }
+
+  function isActive(status) { return !!ACTIVE[status]; }
+  function isTerminal(status) { return !!TERMINAL[status]; }
+
+  // Human label for a status, used identically by the WORK bar and the cards.
+  function statusLabel(status, name, command) {
+    var n = name || 'tool';
+    switch (status) {
+      case STATUS.AWAITING_PERMISSION:
+        return command ? 'Awaiting approval: ' + command : 'Awaiting approval for ' + n;
+      case STATUS.RUNNING:
+      case STATUS.PENDING:
+        return 'Running ' + n;
+      case STATUS.COMPLETED:
+        return 'Completed ' + n;
+      case STATUS.ERROR:
+        return 'Failed ' + n;
+      default:
+        return n;
+    }
+  }
+
+  // Projection mappers — each store keeps its own historical vocabulary; these
+  // translate the ONE canonical status into it so the decision stays centralized.
+  // WORK-bar registry: running | awaiting_permission | completed | failed.
+  function toRegistryStatus(status) {
+    if (status === STATUS.ERROR) return 'failed';
+    if (status === STATUS.PENDING) return 'running';
+    return status; // running | awaiting_permission | completed pass through
+  }
+  // Per-message transcript toolCalls: working | awaiting_permission | done | error.
+  function toLegacyToolStatus(status) {
+    if (status === STATUS.COMPLETED) return 'done';
+    if (status === STATUS.ERROR) return 'error';
+    if (status === STATUS.AWAITING_PERMISSION) return 'awaiting_permission';
+    return 'working'; // pending | running
+  }
+
+  return {
+    STATUS: STATUS,
+    isLifecycleEvent: isLifecycleEvent,
+    toolEventId: toolEventId,
+    toolEventName: toolEventName,
+    isFailureResult: isFailureResult,
+    isAllowDecision: isAllowDecision,
+    nextStatus: nextStatus,
+    isActive: isActive,
+    isTerminal: isTerminal,
+    statusLabel: statusLabel,
+    toRegistryStatus: toRegistryStatus,
+    toLegacyToolStatus: toLegacyToolStatus,
+  };
+});