@trucore/openclaw-atf 0.1.1 → 0.2.0

package/src/tool_response.mjs

@@ -0,0 +1,181 @@
+/**
+ * tool_response.mjs — OpenClaw adapter envelope builder
+ *
+ * ADAPTER LAYER: Wraps universal ATF results into the OpenClaw-specific
+ * response envelope format (content array with text + json items).
+ *
+ * Architecture:
+ *   Universal contract layer (contracts/)  →  platform-agnostic results
+ *   This file (tool_response.mjs)          →  OpenClaw envelope wrapping
+ *
+ * All native OpenClaw tools use these helpers to produce consistent,
+ * machine-readable response shapes. The envelope is OpenClaw-specific;
+ * the payload inside is universal.
+ *
+ * Response contract (OpenClaw envelope):
+ *   Success payload (inside content[].json):
+ *     { status, result, _meta: { plugin_id, plugin_version, tool, ts, backend?, warnings? } }
+ *   Error payload (inside content[].json):
+ *     { status: "error", error, remediation?, _meta: { ... } }
+ *
+ * Exports:
+ *   - nativeToolSuccess(toolName, summary, result, opts?)
+ *   - nativeToolError(toolName, message, opts?)
+ *   - attachBackendMeta(backendResolution)  → backend meta object
+ *   - RESPONSE_STATUS                       → status enum (re-exported from contracts)
+ *
+ * Uses ONLY built-in Node modules + sibling contracts/. No external deps.
+ */
+
+// ---------------------------------------------------------------------------
+// Imports from universal contract layer
+// ---------------------------------------------------------------------------
+
+import {
+  RESPONSE_STATUS as _RESPONSE_STATUS,
+  buildMeta,
+} from "./contracts/index.mjs";
+
+// Re-export for backward compatibility — existing consumers import from here.
+export const RESPONSE_STATUS = _RESPONSE_STATUS;
+
+// ---------------------------------------------------------------------------
+// Constants — OpenClaw-specific adapter identity
+// ---------------------------------------------------------------------------
+
+/**
+ * OpenClaw plugin identity — adapter-specific, maps to universal product_id.
+ * Kept in sync by version consistency tests.
+ */
+const PLUGIN_ID = "trucore-atf";
+const PLUGIN_VERSION = "0.2.0";
+
+// ---------------------------------------------------------------------------
+// Backend meta builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a compact backend metadata object from a BackendResolution.
+ *
+ * @param {object} backendResolution  Output from resolveBackend().
+ * @returns {{ preferred: string, effective: string, fallback_occurred: boolean, fallback_reason: string|null }}
+ */
+export function attachBackendMeta(backendResolution) {
+  if (!backendResolution || typeof backendResolution !== "object") {
+    return {
+      preferred: "unknown",
+      effective: "unknown",
+      fallback_occurred: false,
+      fallback_reason: null,
+    };
+  }
+  return {
+    preferred: backendResolution.preferred_backend ?? "unknown",
+    effective: backendResolution.effective_backend ?? "unknown",
+    fallback_occurred: backendResolution.fallback_occurred ?? false,
+    fallback_reason: backendResolution.fallback_reason ?? null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Success response — OpenClaw adapter envelope
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an OpenClaw-envelope success response for a native tool.
+ *
+ * ADAPTER FUNCTION: Wraps a universal ATF result into the OpenClaw
+ * content-array format. The payload inside content[].json is the
+ * universal result shape.
+ *
+ * Universal payload (inside json):
+ *   { status, result, _meta: { plugin_id, plugin_version, tool, ts, backend?, warnings? } }
+ *
+ * OpenClaw envelope (this function's output):
+ *   { content: [{ type: "text", text }, { type: "json", json: universalPayload }] }
+ *
+ * @param {string} toolName             Tool name (e.g. "atf_health").
+ * @param {string} summary             Human-readable summary line.
+ * @param {object} result              Tool-specific result data.
+ * @param {object} [opts]              Optional overrides.
+ * @param {string} [opts.status]       One of RESPONSE_STATUS values (default: "ok").
+ * @param {object} [opts.backend]      BackendResolution from resolveBackend().
+ * @param {string[]} [opts.warnings]   Operator-facing warnings.
+ * @returns {{ content: Array<{type:string, text?:string, json?:unknown}> }}
+ */
+export function nativeToolSuccess(toolName, summary, result, opts = {}) {
+  // Build universal metadata via the contract layer's builder
+  const universalMeta = buildMeta(toolName, opts);
+
+  // Augment with OpenClaw-specific adapter identity fields
+  const meta = {
+    ...universalMeta,
+    plugin_id: PLUGIN_ID,
+    plugin_version: PLUGIN_VERSION,
+  };
+
+  // Universal payload — same shape regardless of adapter
+  const payload = {
+    status: opts.status ?? RESPONSE_STATUS.OK,
+    result: result ?? {},
+    _meta: meta,
+  };
+
+  // OpenClaw-specific envelope wrapping
+  return {
+    content: [
+      { type: "text", text: summary },
+      { type: "json", json: payload },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error response — OpenClaw adapter envelope
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an OpenClaw-envelope error response for a native tool.
+ *
+ * ADAPTER FUNCTION: Wraps a universal ATF error result into the OpenClaw
+ * content-array format.
+ *
+ * @param {string} toolName            Tool name.
+ * @param {string} message             Human-readable error message.
+ * @param {object} [opts]              Optional overrides.
+ * @param {object} [opts.backend]      BackendResolution from resolveBackend().
+ * @param {string[]} [opts.warnings]   Operator-facing warnings.
+ * @param {string[]} [opts.remediation] Fix instructions.
+ * @returns {{ content: Array<{type:string, text?:string, json?:unknown}>, isError: boolean }}
+ */
+export function nativeToolError(toolName, message, opts = {}) {
+  // Build universal metadata via the contract layer's builder
+  const universalMeta = buildMeta(toolName, opts);
+
+  // Augment with OpenClaw-specific adapter identity fields
+  const meta = {
+    ...universalMeta,
+    plugin_id: PLUGIN_ID,
+    plugin_version: PLUGIN_VERSION,
+  };
+
+  // Universal error payload
+  const payload = {
+    status: RESPONSE_STATUS.ERROR,
+    error: message,
+    _meta: meta,
+  };
+
+  if (Array.isArray(opts.remediation) && opts.remediation.length > 0) {
+    payload.remediation = [...opts.remediation];
+  }
+
+  // OpenClaw-specific envelope wrapping
+  return {
+    content: [
+      { type: "text", text: message },
+      { type: "json", json: payload },
+    ],
+    isError: true,
+  };
+}