@stagewhisper/stagewhisper 0.40.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stagewhisper/stagewhisper",
-  "version": "0.40.0",
+  "version": "0.43.0",
   "type": "module",
   "description": "OpenClaw channel plugin that connects StageWhisper live calls to your AI assistant",
   "license": "MIT",
@@ -8,6 +8,7 @@
     "index.ts",
     "plugin-main.ts",
     "api.ts",
+    "openresponses.d.ts",
     "src",
     "openclaw.plugin.json",
     "skills"

package/plugin-main.ts

@@ -112,6 +112,92 @@ export default definePluginEntry({
             }
           });
 
+        sw.command("reasoning-check")
+          .description("Test reasoning capability against the local OpenResponses endpoint")
+          .option("--model <model>", "Model to use (omit to use your configured default)", "default")
+          .action(async (opts: { model: string }) => {
+            const { callOpenResponses } = await import("./src/openresponses.js");
+            const modelLabel = opts.model === "default" ? "default (configured)" : opts.model;
+            console.log(`Testing reasoning with model: ${modelLabel}`);
+            console.log("Sending test request to local /v1/responses ...");
+
+            const start = Date.now();
+            try {
+              const result = await callOpenResponses(api, {
+                model: opts.model,
+                input: JSON.stringify({
+                  transcript: "Candidate: I think we should use Redis for caching.",
+                  playbook_guidance: "Evaluate technical decisions",
+                }),
+                text: {
+                  format: {
+                    type: "json_schema" as const,
+                    name: "reasoning_test",
+                    schema: {
+                      type: "object",
+                      properties: {
+                        signals: {
+                          type: "array",
+                          items: {
+                            type: "object",
+                            properties: {
+                              severity: { type: "string", enum: ["green", "orange", "red"] },
+                              message: { type: "string" },
+                            },
+                            required: ["severity", "message"],
+                            additionalProperties: false,
+                          },
+                        },
+                        no_signal_reason: { type: "string" },
+                      },
+                      required: ["signals", "no_signal_reason"],
+                      additionalProperties: false,
+                    },
+                    strict: true,
+                  },
+                },
+                temperature: 0.2,
+                max_output_tokens: 1024,
+              });
+
+              const elapsed = Date.now() - start;
+              console.log(`✓ Response received in ${elapsed}ms`);
+              console.log(`  Run ID: ${result.id}`);
+              if (result.usage) {
+                console.log(
+                  `  Tokens: ${result.usage.input_tokens} in / ${result.usage.output_tokens} out`,
+                );
+              }
+
+              const output = result.output;
+              const text = Array.isArray(output)
+                ? (output.find((o) => o.type === "message") as Record<string, unknown> | undefined)
+                : null;
+              const textContent = text
+                ? ((text.content as Array<Record<string, unknown>>)?.find(
+                    (c) => c.type === "output_text",
+                  )?.text as string | undefined)
+                : null;
+              if (textContent) {
+                try {
+                  const parsed = JSON.parse(textContent);
+                  console.log("  Schema-valid JSON: ✓");
+                  console.log(`  Output: ${JSON.stringify(parsed, null, 2)}`);
+                } catch {
+                  console.log("  Schema-valid JSON: ✗ (parse error)");
+                  console.log(`  Raw text: ${textContent.slice(0, 500)}`);
+                }
+              }
+            } catch (err) {
+              const elapsed = Date.now() - start;
+              console.error(`✗ Reasoning check failed after ${elapsed}ms`);
+              console.error(
+                `  Error: ${err instanceof Error ? err.message : String(err)}`,
+              );
+              process.exitCode = 1;
+            }
+          });
+
         sw.command("status")
           .description("Show StageWhisper relay connection status")
           .action(async () => {

package/src/client.ts

@@ -37,10 +37,7 @@ export class StageWhisperClient {
     };
   }
 
-  async completePairing(
-    pairingCode: string,
-    hostLabel: string,
-  ): Promise<PairCompleteResponse> {
+  async completePairing(pairingCode: string, hostLabel: string): Promise<PairCompleteResponse> {
     const res = await fetch(`${this.baseUrl}/api/v1/openclaw/pair/complete`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -56,22 +53,15 @@ export class StageWhisperClient {
     return res.json();
   }
 
-  async updateTaskStatus(
-    taskId: string,
-    status: string,
-    remoteTaskId?: string,
-  ): Promise<void> {
+  async updateTaskStatus(taskId: string, status: string, remoteTaskId?: string): Promise<void> {
     const body: Record<string, unknown> = { status };
     if (remoteTaskId) body.remote_task_id = remoteTaskId;
 
-    const res = await fetch(
-      `${this.baseUrl}/api/v1/openclaw/tasks/${taskId}/status`,
-      {
-        method: "POST",
-        headers: this.headers(),
-        body: JSON.stringify(body),
-      },
-    );
+    const res = await fetch(`${this.baseUrl}/api/v1/openclaw/tasks/${taskId}/status`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(body),
+    });
     if (!res.ok) {
       const text = await res.text();
       throw new Error(`Status update failed (${res.status}): ${text}`);
@@ -82,26 +72,24 @@ export class StageWhisperClient {
     const body: Record<string, unknown> = { content };
     if (remoteMessageId) body.remote_message_id = remoteMessageId;
 
-    const res = await fetch(
-      `${this.baseUrl}/api/v1/openclaw/tasks/${taskId}/reply`,
-      {
-        method: "POST",
-        headers: this.headers(),
-        body: JSON.stringify(body),
-      },
-    );
+    const res = await fetch(`${this.baseUrl}/api/v1/openclaw/tasks/${taskId}/reply`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(body),
+    });
     if (!res.ok) {
       const text = await res.text();
       throw new Error(`Reply failed (${res.status}): ${text}`);
     }
   }
 
-  async heartbeat(): Promise<HeartbeatResponse> {
+  async heartbeat(capabilities?: Record<string, unknown>): Promise<HeartbeatResponse> {
     const res = await fetch(
       `${this.baseUrl}/api/v1/openclaw/integrations/${this.integrationId}/heartbeat`,
       {
         method: "POST",
         headers: this.headers(),
+        body: capabilities ? JSON.stringify(capabilities) : undefined,
       },
     );
     if (!res.ok) {
@@ -111,6 +99,26 @@ export class StageWhisperClient {
     return res.json();
   }
 
+  async postReasoningResult(
+    jobId: string,
+    result: Record<string, unknown>,
+    correlationId?: string,
+  ): Promise<void> {
+    const headers = this.headers();
+    if (correlationId) {
+      headers["X-Correlation-ID"] = correlationId;
+    }
+    const res = await fetch(`${this.baseUrl}/api/v1/openclaw/reasoning-jobs/${jobId}/complete`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(result),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Reasoning result post failed (${res.status}): ${text}`);
+    }
+  }
+
   streamUrl(): string {
     return `${this.baseUrl}/api/v1/openclaw/integrations/${this.integrationId}/stream`;
   }

package/src/health.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "vitest";
+import { createHealthTracker } from "./health.js";
+
+describe("createHealthTracker", () => {
+  it("starts unverified", () => {
+    const tracker = createHealthTracker("gpt-4o");
+    const caps = tracker.get();
+    expect(caps.status).toBe("unverified");
+    expect(caps.supportsReasoning).toBe(true);
+    expect(caps.displayModel).toBe("gpt-4o");
+    expect(caps.consecutiveFailures).toBe(0);
+  });
+
+  it("records success and updates lastHealthyAt", () => {
+    const tracker = createHealthTracker(null);
+    tracker.recordFailure("timeout");
+    tracker.recordSuccess();
+    const caps = tracker.get();
+    expect(caps.status).toBe("healthy");
+    expect(caps.consecutiveFailures).toBe(0);
+    expect(caps.lastHealthyAt).toBeInstanceOf(Date);
+  });
+
+  it("degrades after 3 consecutive failures", () => {
+    const tracker = createHealthTracker(null);
+    tracker.recordFailure("err1");
+    tracker.recordFailure("err2");
+    expect(tracker.get().status).toBe("unverified");
+    tracker.recordFailure("err3");
+    expect(tracker.get().status).toBe("degraded");
+    expect(tracker.get().degradedReason).toBe("err3");
+  });
+
+  it("sets auth_required on 401/403 errors", () => {
+    const tracker = createHealthTracker(null);
+    tracker.recordFailure("401 Unauthorized");
+    expect(tracker.get().status).toBe("auth_required");
+  });
+
+  it("setModel updates displayModel", () => {
+    const tracker = createHealthTracker("gpt-4o");
+    tracker.setModel("claude-4");
+    expect(tracker.get().displayModel).toBe("claude-4");
+  });
+
+  it("setDisabled marks disabled", () => {
+    const tracker = createHealthTracker(null);
+    tracker.setDisabled();
+    const caps = tracker.get();
+    expect(caps.status).toBe("disabled");
+    expect(caps.supportsReasoning).toBe(false);
+  });
+
+  it("toHeartbeatPayload serializes snake_case", () => {
+    const tracker = createHealthTracker("gpt-4o");
+    tracker.recordSuccess();
+    const payload = tracker.toHeartbeatPayload();
+    expect(payload).toMatchObject({
+      supports_assistant_tasks: true,
+      supports_reasoning: true,
+      reasoning_transport: "openresponses",
+      display_model: "gpt-4o",
+      provider_ref: "openclaw",
+      status: "healthy",
+      degraded_reason: null,
+    });
+  });
+
+  it("get returns a copy, not the internal state", () => {
+    const tracker = createHealthTracker(null);
+    const caps = tracker.get();
+    caps.status = "disabled";
+    expect(tracker.get().status).toBe("unverified");
+  });
+
+  it("setDisconnected marks disconnected and setConnected restores", () => {
+    const tracker = createHealthTracker(null);
+    tracker.recordSuccess();
+    expect(tracker.get().status).toBe("healthy");
+
+    tracker.setDisconnected();
+    expect(tracker.get().status).toBe("disconnected");
+
+    tracker.setConnected();
+    expect(tracker.get().status).toBe("healthy");
+  });
+
+  it("setDisconnected does not override disabled", () => {
+    const tracker = createHealthTracker(null);
+    tracker.setDisabled();
+    tracker.setDisconnected();
+    expect(tracker.get().status).toBe("disabled");
+  });
+
+  it("setConnected is a no-op when not disconnected", () => {
+    const tracker = createHealthTracker(null);
+    tracker.recordSuccess();
+    tracker.setConnected();
+    expect(tracker.get().status).toBe("healthy");
+  });
+});

package/src/health.ts

@@ -0,0 +1,94 @@
+export type HostHealthStatus =
+  | "healthy"
+  | "degraded"
+  | "disconnected"
+  | "auth_required"
+  | "disabled"
+  | "unverified";
+
+export type HostCapabilities = {
+  supportsAssistantTasks: boolean;
+  supportsReasoning: boolean;
+  reasoningTransport: string | null;
+  displayModel: string | null;
+  providerRef: string;
+  status: HostHealthStatus;
+  degradedReason: string | null;
+  lastHealthyAt: Date | null;
+  consecutiveFailures: number;
+};
+
+const DEGRADED_THRESHOLD = 3;
+
+export function createHealthTracker(initialModel: string | null) {
+  const state: HostCapabilities = {
+    supportsAssistantTasks: true,
+    supportsReasoning: true,
+    reasoningTransport: "openresponses",
+    displayModel: initialModel,
+    providerRef: "openclaw",
+    status: "unverified",
+    degradedReason: null,
+    lastHealthyAt: null,
+    consecutiveFailures: 0,
+  };
+
+  let statusBeforeDisconnect: HostHealthStatus | null = null;
+
+  return {
+    get: (): HostCapabilities => ({ ...state }),
+
+    recordSuccess() {
+      state.consecutiveFailures = 0;
+      state.status = "healthy";
+      state.degradedReason = null;
+      state.lastHealthyAt = new Date();
+      statusBeforeDisconnect = null;
+    },
+
+    recordFailure(reason: string) {
+      state.consecutiveFailures += 1;
+      state.degradedReason = reason;
+      if (reason.includes("401") || reason.includes("403")) {
+        state.status = "auth_required";
+      } else if (state.consecutiveFailures >= DEGRADED_THRESHOLD) {
+        state.status = "degraded";
+      }
+    },
+
+    setModel(model: string) {
+      state.displayModel = model;
+    },
+
+    setDisabled() {
+      state.status = "disabled";
+      state.supportsReasoning = false;
+    },
+
+    setDisconnected() {
+      if (state.status !== "disabled") {
+        statusBeforeDisconnect = state.status;
+        state.status = "disconnected";
+      }
+    },
+
+    setConnected() {
+      if (state.status === "disconnected" && statusBeforeDisconnect !== null) {
+        state.status = statusBeforeDisconnect;
+        statusBeforeDisconnect = null;
+      }
+    },
+
+    toHeartbeatPayload(): Record<string, unknown> {
+      return {
+        supports_assistant_tasks: state.supportsAssistantTasks,
+        supports_reasoning: state.supportsReasoning,
+        reasoning_transport: state.reasoningTransport,
+        display_model: state.displayModel,
+        provider_ref: state.providerRef,
+        status: state.status,
+        degraded_reason: state.degradedReason,
+      };
+    },
+  };
+}

package/src/openresponses.ts

@@ -0,0 +1,101 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+
+type GatewayConfig = { url: string; apiKey: string | null };
+
+function resolveGatewayConfig(api: OpenClawPluginApi): GatewayConfig {
+  const cfg = api.config as Record<string, unknown>;
+  const gw = (cfg?.gateway as Record<string, unknown>) ?? {};
+  const url = String(gw?.url ?? "http://127.0.0.1:18789").replace(/\/+$/, "");
+  const rawKey = typeof gw?.apiKey === "string" ? gw.apiKey : null;
+
+  let apiKey: string | null = null;
+  if (rawKey) {
+    try {
+      const parsed = new URL(url);
+      const safe =
+        parsed.hostname === "localhost" ||
+        parsed.hostname === "127.0.0.1" ||
+        parsed.hostname === "::1" ||
+        parsed.protocol === "https:";
+      apiKey = safe ? rawKey : null;
+    } catch {
+      apiKey = null;
+    }
+  }
+
+  return { url, apiKey };
+}
+
+export async function callOpenResponses(
+  api: OpenClawPluginApi,
+  requestBody: OpenResponsesCreateResponseRequestBody,
+  signal?: AbortSignal,
+  correlationId?: string,
+): Promise<OpenResponsesResponseResource> {
+  const gw = resolveGatewayConfig(api);
+  const url = `${gw.url}/v1/responses`;
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (gw.apiKey) {
+    headers["Authorization"] = `Bearer ${gw.apiKey}`;
+  }
+  if (correlationId) {
+    headers["X-Correlation-ID"] = correlationId;
+  }
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(requestBody),
+    signal,
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new OpenResponsesError(`POST /v1/responses returned ${response.status}: ${body}`, response.status);
+  }
+  return (await response.json()) as OpenResponsesResponseResource;
+}
+
+export class OpenResponsesError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number,
+  ) {
+    super(message);
+    this.name = "OpenResponsesError";
+  }
+
+  get retryable(): boolean {
+    return (
+      this.statusCode === 408 ||
+      this.statusCode === 429 ||
+      (this.statusCode >= 500 && this.statusCode < 600)
+    );
+  }
+}
+
+export type { components, operations, paths, webhooks } from "../openresponses";
+
+export type OpenResponsesCreateResponseOperation =
+  import("../openresponses").operations["createResponse"];
+export type OpenResponsesCreateResponseRequestBody =
+  import("../openresponses").components["schemas"]["CreateResponseBody"];
+export type OpenResponsesResponseResource =
+  import("../openresponses").components["schemas"]["ResponseResource"];
+export type OpenResponsesRequestItem =
+  import("../openresponses").components["schemas"]["ItemParam"];
+export type OpenResponsesResponseItem =
+  import("../openresponses").components["schemas"]["ItemField"];
+export type OpenResponsesTool =
+  import("../openresponses").components["schemas"]["ResponsesToolParam"];
+export type OpenResponsesToolChoice =
+  import("../openresponses").components["schemas"]["ToolChoiceParam"];
+export type OpenResponsesTextFormat =
+  import("../openresponses").components["schemas"]["TextFormatParam"];
+export type OpenResponsesReasoning =
+  import("../openresponses").components["schemas"]["ReasoningParam"];
+export type OpenResponsesStreamEvent =
+  import("../openresponses").operations["createResponse"]["responses"][200]["content"]["text/event-stream"];

package/src/reasoning.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { executeReasoningJob, type ReasoningJobEnvelope } from "./reasoning.js";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+
+vi.mock("./openresponses.js", () => ({
+  callOpenResponses: vi.fn(),
+  OpenResponsesError: class extends Error {
+    status: number;
+    retryable: boolean;
+    constructor(message: string, status: number) {
+      super(message);
+      this.status = status;
+      this.retryable = status >= 500;
+    }
+  },
+}));
+
+const { callOpenResponses, OpenResponsesError } = await import("./openresponses.js");
+const mockCall = vi.mocked(callOpenResponses);
+
+function makeApi(): OpenClawPluginApi {
+  return {
+    logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+    config: { get: vi.fn().mockReturnValue({}) },
+  } as unknown as OpenClawPluginApi;
+}
+
+function makeJob(overrides: Partial<ReasoningJobEnvelope> = {}): ReasoningJobEnvelope {
+  return {
+    event_type: "reasoning_job",
+    job_id: "job-123",
+    purpose: "live_analysis",
+    deadline_at: new Date(Date.now() + 30_000).toISOString(),
+    idempotency_key: "idem-1",
+    schema_version: 1,
+    response_schema: {
+      type: "object",
+      properties: { signals: { type: "array" } },
+      required: ["signals"],
+    },
+    payload: { transcript: "Hello world" },
+    ...overrides,
+  };
+}
+
+describe("executeReasoningJob", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns completed with parsed JSON output", async () => {
+    mockCall.mockResolvedValue({
+      id: "resp-abc",
+      model: "gpt-4o",
+      output: [
+        {
+          type: "message",
+          content: [
+            { type: "output_text", text: '{"signals": [{"severity": "green", "message": "ok"}]}' },
+          ],
+        },
+      ],
+      usage: { input_tokens: 100, output_tokens: 50 },
+    } as never);
+
+    const result = await executeReasoningJob(makeApi(), makeJob(), "gpt-4o");
+    expect(result.status).toBe("completed");
+    expect(result.job_id).toBe("job-123");
+    expect(result.output).toEqual({ signals: [{ severity: "green", message: "ok" }] });
+    expect(result.usage).toEqual({ input_tokens: 100, output_tokens: 50 });
+    expect(result.provider_run_id).toBe("resp-abc");
+  });
+
+  it("returns timed_out when deadline already passed", async () => {
+    const job = makeJob({ deadline_at: new Date(Date.now() - 1000).toISOString() });
+    const result = await executeReasoningJob(makeApi(), job, "gpt-4o");
+    expect(result.status).toBe("timed_out");
+    expect(result.error_code).toBe("deadline_expired_before_start");
+    expect(mockCall).not.toHaveBeenCalled();
+  });
+
+  it("returns failed when output is not valid JSON", async () => {
+    mockCall.mockResolvedValue({
+      id: "resp-bad",
+      output: [
+        { type: "message", content: [{ type: "output_text", text: "not json" }] },
+      ],
+      usage: { input_tokens: 10, output_tokens: 5 },
+    } as never);
+
+    const result = await executeReasoningJob(makeApi(), makeJob(), "gpt-4o");
+    expect(result.status).toBe("failed");
+    expect(result.error_code).toBe("response_parse_error");
+  });
+
+  it("returns failed with retryable flag on 5xx errors", async () => {
+    const err = new (OpenResponsesError as unknown as new (msg: string, status: number) => Error & { retryable: boolean })(
+      "Internal Server Error",
+      500,
+    );
+    mockCall.mockRejectedValue(err);
+
+    const result = await executeReasoningJob(makeApi(), makeJob(), "gpt-4o");
+    expect(result.status).toBe("failed");
+    expect(result.error_code).toBe("retryable_error");
+  });
+
+  it("returns failed with execution_error on non-retryable errors", async () => {
+    mockCall.mockRejectedValue(new Error("Network failure"));
+
+    const result = await executeReasoningJob(makeApi(), makeJob(), "gpt-4o");
+    expect(result.status).toBe("failed");
+    expect(result.error_code).toBe("execution_error");
+    expect(result.error_message).toBe("Network failure");
+  });
+});