@cavi-ai/api-client 0.1.0

package/src/providers/hermes/agent-config.ts

@@ -0,0 +1,322 @@
+import {
+  GatewayAgentConfigApiClient,
+  GatewayAgentConfigApiError,
+  assertAgentProfileId,
+  buildAgentConfigFromConfigSnapshot,
+  findAgentProfile,
+  isMissingAgentConfigRouteError,
+  normalizeAgentProfiles,
+  setAgentConfigPathValue,
+  type AgentConfig,
+  type AgentConfigDraftDiff,
+  type AgentProfileSummary,
+  type GatewayConfigSchemaField,
+  type PatchProfileConfigOptions,
+} from "../../core/gateway/agent/config.js";
+import { isSensitiveKey } from "../../core/http/redaction.js";
+import { HERMES_AGENT_CONFIG_API_ENDPOINTS } from "../../contracts/paths.js";
+import type { HttpApiClientOptions } from "../../core/http/types.js";
+
+/** Cookie the Hermes host-config plugin reads to select the active profile. */
+export const HERMES_PROFILE_COOKIE_NAME = "hermes_profile";
+
+const REASONING_EFFORT_OPTIONS = [
+  { value: "", label: "Default" },
+  { value: "none", label: "None" },
+  { value: "minimal", label: "Minimal" },
+  { value: "low", label: "Low" },
+  { value: "medium", label: "Medium" },
+  { value: "high", label: "High" },
+  { value: "xhigh", label: "Extra high" },
+] as const;
+
+function cleanString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function asArray(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function asBoolean(value: unknown): boolean | null {
+  return typeof value === "boolean" ? value : null;
+}
+
+export function hermesAgentProfileConfigYamlPath(agentId: string): string {
+  const id = assertAgentProfileId(agentId);
+  return id === "default"
+    ? "~/.hermes/config.yaml"
+    : `~/.hermes/profiles/${id}/config.yaml`;
+}
+
+export function hermesProfileCookieHeader(agentId: string): string {
+  return `${HERMES_PROFILE_COOKIE_NAME}=${assertAgentProfileId(agentId)}`;
+}
+
+function modelOptionsFromHermesWebuiSnapshot(
+  modelsPayload: unknown,
+): readonly { value: string; label: string }[] {
+  const options: { value: string; label: string }[] = [];
+  for (const groupValue of asArray(asRecord(modelsPayload).groups)) {
+    const group = asRecord(groupValue);
+    for (const modelValue of asArray(group.models)) {
+      const model = asRecord(modelValue);
+      const value = cleanString(model.id) || cleanString(model.value) || cleanString(model.name);
+      if (!value) continue;
+      options.push({
+        value,
+        label: cleanString(model.label) || cleanString(model.name) || value,
+      });
+    }
+  }
+  return options;
+}
+
+function mcpServerNamesFromHermesWebuiSnapshot(mcpServersPayload: unknown): string[] {
+  return asArray(asRecord(mcpServersPayload).servers)
+    .map((value) => {
+      if (typeof value === "string") return cleanString(value);
+      const server = asRecord(value);
+      return cleanString(server.name) || cleanString(server.id);
+    })
+    .filter(Boolean);
+}
+
+function buildHermesWebuiSnapshotConfig(input: {
+  config?: unknown;
+  models?: unknown;
+  reasoning?: unknown;
+  mcpServers?: unknown;
+}): Record<string, unknown> {
+  const config = asRecord(input.config);
+  if (Object.keys(config).length > 0) return config;
+
+  let synthetic: Record<string, unknown> = {};
+  const models = asRecord(input.models);
+  const defaultModel = cleanString(models.default_model);
+  if (defaultModel) {
+    synthetic = setAgentConfigPathValue(synthetic, "model.default", defaultModel);
+  }
+  const activeProvider = cleanString(models.active_provider);
+  if (activeProvider) {
+    synthetic = setAgentConfigPathValue(synthetic, "model.provider", activeProvider);
+  }
+
+  const reasoning = asRecord(input.reasoning);
+  const reasoningEffort = cleanString(reasoning.reasoning_effort);
+  if (reasoningEffort) {
+    synthetic = setAgentConfigPathValue(synthetic, "agent.reasoning_effort", reasoningEffort);
+  }
+  const showReasoning = asBoolean(reasoning.show_reasoning);
+  if (showReasoning !== null) {
+    synthetic = setAgentConfigPathValue(synthetic, "display.show_reasoning", showReasoning);
+  }
+
+  const mcpServers = mcpServerNamesFromHermesWebuiSnapshot(input.mcpServers);
+  if (mcpServers.length > 0) {
+    synthetic = setAgentConfigPathValue(synthetic, "mcp_servers.enabled", mcpServers);
+  }
+
+  return synthetic;
+}
+
+function buildHermesWebuiSnapshotSchema(input: {
+  schema?: unknown;
+  models?: unknown;
+  reasoning?: unknown;
+  mcpServers?: unknown;
+}): unknown {
+  const schema = asRecord(input.schema);
+  if (Object.keys(schema).length > 0) return schema;
+
+  const fields: Record<string, GatewayConfigSchemaField> = {};
+  const modelOptions = modelOptionsFromHermesWebuiSnapshot(input.models);
+  if (cleanString(asRecord(input.models).default_model)) {
+    fields["model.default"] = {
+      type: modelOptions.length > 0 ? "select" : "string",
+      category: "model",
+      description: "Default model",
+      ...(modelOptions.length > 0 ? { options: modelOptions } : {}),
+    };
+  }
+  if (cleanString(asRecord(input.models).active_provider)) {
+    fields["model.provider"] = {
+      type: "string",
+      category: "model",
+      description: "Active provider",
+    };
+  }
+  if (cleanString(asRecord(input.reasoning).reasoning_effort)) {
+    fields["agent.reasoning_effort"] = {
+      type: "select",
+      category: "agent",
+      description: "Reasoning effort",
+      options: REASONING_EFFORT_OPTIONS,
+    };
+  }
+  if (asBoolean(asRecord(input.reasoning).show_reasoning) !== null) {
+    fields["display.show_reasoning"] = {
+      type: "boolean",
+      category: "display",
+      description: "Show reasoning",
+    };
+  }
+  if (mcpServerNamesFromHermesWebuiSnapshot(input.mcpServers).length > 0) {
+    fields["mcp_servers.enabled"] = {
+      type: "list",
+      category: "mcp_servers",
+      description: "Enabled MCP servers",
+    };
+  }
+
+  return Object.keys(fields).length > 0
+    ? { fields, category_order: ["model", "agent", "mcp_servers", "display"] }
+    : {};
+}
+
+export function buildAgentConfigFromHermesConfigSnapshot(input: {
+  agentId: string;
+  config: unknown;
+  schema?: unknown;
+  defaults?: unknown;
+  profile?: AgentProfileSummary | null;
+  fetchedAt?: number;
+  etag?: string;
+}): AgentConfig {
+  return buildAgentConfigFromConfigSnapshot({
+    ...input,
+    defaultSourcePath: hermesAgentProfileConfigYamlPath,
+  });
+}
+
+export function buildAgentConfigFromHermesWebuiSnapshot(input: {
+  agentId: string;
+  profile?: AgentProfileSummary | null;
+  profiles?: unknown;
+  config?: unknown;
+  schema?: unknown;
+  defaults?: unknown;
+  models?: unknown;
+  reasoning?: unknown;
+  mcpServers?: unknown;
+  fetchedAt?: number;
+  etag?: string;
+}): AgentConfig {
+  const agentId = assertAgentProfileId(input.agentId);
+  const profile =
+    input.profile ??
+    findAgentProfile(normalizeAgentProfiles(input.profiles), agentId) ??
+    null;
+  return buildAgentConfigFromHermesConfigSnapshot({
+    agentId,
+    profile,
+    config: buildHermesWebuiSnapshotConfig(input),
+    schema: buildHermesWebuiSnapshotSchema(input),
+    defaults: input.defaults,
+    fetchedAt: input.fetchedAt,
+    etag: input.etag,
+  });
+}
+
+function unsupportedHermesWebuiPatchKeys(diff: AgentConfigDraftDiff): string[] {
+  return Object.keys(diff).filter((key) => {
+    return key.startsWith("profile.") || isSensitiveKey(key);
+  });
+}
+
+export class HermesAgentConfigApiClient extends GatewayAgentConfigApiClient {
+  constructor(options: HttpApiClientOptions) {
+    super(options, {
+      endpoints: HERMES_AGENT_CONFIG_API_ENDPOINTS,
+      surface: "hermes-agent-config-api",
+      defaultSourcePath: hermesAgentProfileConfigYamlPath,
+    });
+  }
+
+  override async getProfileConfig(agentId: string): Promise<AgentConfig> {
+    const id = assertAgentProfileId(agentId);
+    try {
+      return await super.getProfileConfig(id);
+    } catch (error) {
+      if (!isMissingAgentConfigRouteError(error)) throw error;
+      return this.getProfileConfigViaHermesWebui(id);
+    }
+  }
+
+  private async getProfileConfigViaHermesWebui(agentId: string): Promise<AgentConfig> {
+    const id = assertAgentProfileId(agentId);
+    const profiles = normalizeAgentProfiles(
+      await this.requestJson<unknown>(this.endpoints.profiles),
+    );
+    const profile = findAgentProfile(profiles, id);
+    if (!profile && id !== "default") {
+      throw new GatewayAgentConfigApiError(`Agent profile "${id}" was not found.`, {
+        path: this.endpoints.profiles,
+        status: 404,
+      });
+    }
+
+    const headers = { Cookie: hermesProfileCookieHeader(id) };
+    const [config, schema, defaults] = await Promise.all([
+      this.requestJson<unknown>(this.endpoints.config, { headers }),
+      this.requestJson<unknown>(this.endpoints.configSchema, { headers }),
+      this.requestJson<unknown>(this.endpoints.configDefaults, { headers }),
+    ]);
+
+    return buildAgentConfigFromHermesWebuiSnapshot({
+      agentId: id,
+      profile,
+      config,
+      schema,
+      defaults,
+      fetchedAt: Date.now(),
+    });
+  }
+
+  override async patchProfileConfig(
+    agentId: string,
+    diff: AgentConfigDraftDiff,
+    options: PatchProfileConfigOptions = {},
+  ): Promise<AgentConfig> {
+    const id = assertAgentProfileId(agentId);
+    try {
+      return await super.patchProfileConfig(id, diff, options);
+    } catch (error) {
+      if (!isMissingAgentConfigRouteError(error)) throw error;
+      return this.patchProfileConfigViaHermesWebui(id, diff);
+    }
+  }
+
+  private async patchProfileConfigViaHermesWebui(
+    agentId: string,
+    diff: AgentConfigDraftDiff,
+  ): Promise<AgentConfig> {
+    const id = assertAgentProfileId(agentId);
+    const unsupported = unsupportedHermesWebuiPatchKeys(diff);
+    if (unsupported.length > 0) {
+      throw new GatewayAgentConfigApiError(
+        `These config keys are not editable through the mobile editor: ${unsupported.join(", ")}.`,
+      );
+    }
+
+    const headers = { Cookie: hermesProfileCookieHeader(id) };
+    let nextConfig = asRecord(await this.requestJson<unknown>(this.endpoints.config, { headers }));
+    for (const [key, value] of Object.entries(diff)) {
+      if (value === undefined) continue;
+      nextConfig = setAgentConfigPathValue(nextConfig, key, value);
+    }
+    await this.requestJson(this.endpoints.config, {
+      method: "PUT",
+      headers,
+      body: { config: nextConfig },
+    });
+
+    return this.getProfileConfigViaHermesWebui(id);
+  }
+}

package/src/providers/hermes/chat-run.ts

@@ -0,0 +1,340 @@
+import {
+  RUN_STREAM_EVENT_NAMES,
+  type RunStreamApprovalChoice,
+  type RunStreamEvent,
+} from "../../core/gateway/run/contracts.js";
+import { HERMES_API_ENDPOINTS } from "../../contracts/paths.js";
+import { HermesSseRunEventProvider } from "./sse-run-event-provider.js";
+import {
+  RunPreviewPollProvider,
+  createRunStreamWithToolFallback,
+  type RunEventStreamSubscription,
+  type RunPreviewSnapshotFetcher,
+} from "../../core/gateway/run/event-stream.js";
+
+/**
+ * Provider-neutral metadata bag attached to a Hermes chat run. Free-form by
+ * design — the gateway forwards untyped fields to route handlers. Use
+ * {@link sanitizeHermesRouteMetadata} before sending to strip dict-valued
+ * route binding keys some routers reject as malformed.
+ */
+export type HermesRouteMetadata = Record<string, unknown>;
+export type GatewayRouteMetadata = HermesRouteMetadata;
+
+const DICT_REJECTING_ROUTE_METADATA_KEYS = new Set(["binding", "routeBinding"]);
+
+function isDict(value: unknown): boolean {
+  return Boolean(value) && typeof value === "object";
+}
+
+/**
+ * Gateway route bindings are scalar fields (`targetProfile`, `targetAgent`,
+ * `sessionKey`, `action`). Some routers validate dict-valued `binding` /
+ * `routeBinding` keys and reject the whole chat turn — strip those before
+ * forwarding metadata.
+ */
+export function sanitizeHermesRouteMetadata(
+  metadata: HermesRouteMetadata | undefined,
+): HermesRouteMetadata | undefined {
+  if (!metadata || Object.keys(metadata).length === 0) {
+    return undefined;
+  }
+  const out: HermesRouteMetadata = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (DICT_REJECTING_ROUTE_METADATA_KEYS.has(key) && isDict(value)) {
+      continue;
+    }
+    out[key] = value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+export const sanitizeGatewayRouteMetadata = sanitizeHermesRouteMetadata;
+
+/**
+ * A file sent with a chat turn. Base64 keeps it on the HTTP run path (gateway
+ * field names are sent in snake AND camel case so the server can read whichever
+ * casing it accepts).
+ */
+export type HermesChatRunAttachment = {
+  name: string;
+  mimeType: string;
+  size: number;
+  /** Base64-encoded file bytes (no data: prefix). */
+  dataBase64: string;
+};
+export type GatewayChatRunAttachment = HermesChatRunAttachment;
+
+function serializeAttachments(
+  attachments: readonly HermesChatRunAttachment[],
+): Record<string, unknown>[] {
+  return attachments.map((a) => ({
+    name: a.name,
+    mime_type: a.mimeType,
+    mimeType: a.mimeType,
+    size: a.size,
+    data_base64: a.dataBase64,
+    dataBase64: a.dataBase64,
+  }));
+}
+
+function addOptionalRunField(
+  body: Record<string, unknown>,
+  key: string,
+  value: string | undefined,
+): void {
+  const trimmed = value?.trim();
+  if (trimmed) body[key] = trimmed;
+}
+
+export type StartHermesChatRunParams = {
+  httpBase: string;
+  authToken: string;
+  clientId: string;
+  input: string;
+  sessionId: string;
+  /** Defaults to {@link sessionId} when omitted. */
+  sessionKey?: string;
+  targetProfile?: string;
+  targetAgent?: string;
+  action?: string;
+  metadata?: HermesRouteMetadata;
+  attachments?: readonly HermesChatRunAttachment[];
+  signal?: AbortSignal;
+};
+export type StartGatewayChatRunParams = StartHermesChatRunParams;
+
+/**
+ * Starts a Hermes chat run through the configured run endpoint. Sends route binding fields in
+ * both snake AND camel case for cross-version gateway compatibility. Sanitizes
+ * metadata via {@link sanitizeHermesRouteMetadata} before forwarding.
+ *
+ * Returns the new `run_id`. Pair with {@link HermesSseRunEventProvider} or
+ * {@link streamHermesChatRun} to consume the event stream.
+ */
+export async function startHermesChatRun(
+  params: StartHermesChatRunParams,
+): Promise<{ runId: string }> {
+  const sessionKey = params.sessionKey?.trim() || params.sessionId;
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+    "X-Portal-Client-Id": params.clientId,
+    "X-Hermes-Session-Key": sessionKey,
+  };
+  if (params.authToken.trim()) {
+    headers.Authorization = `Bearer ${params.authToken.trim()}`;
+  }
+
+  const body: Record<string, unknown> = {
+    input: params.input,
+    session_id: params.sessionId,
+  };
+  addOptionalRunField(body, "targetProfile", params.targetProfile);
+  addOptionalRunField(body, "target_profile", params.targetProfile);
+  addOptionalRunField(body, "targetAgent", params.targetAgent);
+  addOptionalRunField(body, "target_agent", params.targetAgent);
+  addOptionalRunField(body, "action", params.action);
+
+  if (params.metadata && Object.keys(params.metadata).length > 0) {
+    const sanitized = sanitizeHermesRouteMetadata(params.metadata);
+    if (sanitized) body.metadata = sanitized;
+  }
+  if (params.attachments && params.attachments.length > 0) {
+    body.attachments = serializeAttachments(params.attachments);
+  }
+
+  const response = await fetch(`${params.httpBase}${HERMES_API_ENDPOINTS.runs}`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    cache: "no-store",
+    signal: params.signal,
+  });
+
+  if (!response.ok) {
+    throw new Error(`run start failed with HTTP ${response.status}`);
+  }
+  const payload = (await response.json()) as { run_id?: string };
+  const runId = typeof payload.run_id === "string" ? payload.run_id : "";
+  if (!runId) {
+    throw new Error("run start missing run_id");
+  }
+  return { runId };
+}
+
+export const startGatewayChatRun = startHermesChatRun;
+
+export type ResolveHermesChatRunApprovalParams = {
+  httpBase: string;
+  authToken: string;
+  clientId: string;
+  runId: string;
+  choice: RunStreamApprovalChoice;
+  sessionKey?: string;
+  signal?: AbortSignal;
+};
+export type ResolveGatewayChatRunApprovalParams = ResolveHermesChatRunApprovalParams;
+
+/**
+ * Resolves a pending approval gate through the configured run approval endpoint with
+ * one of the canonical {@link RunStreamApprovalChoice} options.
+ */
+export async function resolveHermesChatRunApproval(
+  params: ResolveHermesChatRunApprovalParams,
+): Promise<void> {
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+    "X-Portal-Client-Id": params.clientId,
+  };
+  if (params.authToken.trim()) {
+    headers.Authorization = `Bearer ${params.authToken.trim()}`;
+  }
+  if (params.sessionKey?.trim()) {
+    headers["X-Hermes-Session-Key"] = params.sessionKey.trim();
+  }
+  const response = await fetch(
+    `${params.httpBase}${HERMES_API_ENDPOINTS.runApproval(params.runId)}`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ choice: params.choice }),
+      cache: "no-store",
+      signal: params.signal,
+    },
+  );
+  if (!response.ok) {
+    throw new Error(`approval resolve failed with HTTP ${response.status}`);
+  }
+}
+
+export const resolveGatewayChatRunApproval = resolveHermesChatRunApproval;
+
+export type StreamHermesChatRunResult = {
+  /**
+   * True when at least one terminal lifecycle event was observed (delta /
+   * completed / failed / cancelled). Callers use this to detect a silent
+   * stream (no response) and trigger a fallback transport.
+   */
+  sawAssistantResponseEvent: boolean;
+};
+export type StreamGatewayChatRunResult = StreamHermesChatRunResult;
+
+export type StreamHermesChatRunParams = StartHermesChatRunParams & {
+  onEvent: (event: RunStreamEvent) => void;
+  /**
+   * Optional snapshot fetcher — when present, composes a tool-event fallback
+   * via {@link RunPreviewPollProvider} so tool calls land in the stream even
+   * when the Hermes SSE doesn't surface them. Once Hermes SSE catches up on
+   * tool events, the fallback becomes a no-op automatically.
+   */
+  fetchToolEventSnapshot?: RunPreviewSnapshotFetcher;
+};
+export type StreamGatewayChatRunParams = StreamHermesChatRunParams;
+
+/**
+ * Canonical orchestrator: starts a Hermes chat run, subscribes to its event
+ * stream via {@link HermesSseRunEventProvider}, and optionally stitches in
+ * tool events from the post-hoc run preview via
+ * {@link createRunStreamWithToolFallback}. Consumers receive canonical
+ * {@link RunStreamEvent}s on `onEvent` — switch on `event.event` against
+ * {@link RUN_STREAM_EVENT_NAMES}, never inline strings.
+ */
+export async function streamHermesChatRun(
+  params: StreamHermesChatRunParams,
+): Promise<StreamHermesChatRunResult> {
+  const sessionKey = params.sessionKey?.trim() || params.sessionId;
+  const { runId } = await startHermesChatRun({
+    httpBase: params.httpBase,
+    authToken: params.authToken,
+    clientId: params.clientId,
+    input: params.input,
+    sessionId: params.sessionId,
+    sessionKey,
+    targetProfile: params.targetProfile,
+    targetAgent: params.targetAgent,
+    action: params.action,
+    metadata: params.metadata,
+    attachments: params.attachments,
+    signal: params.signal,
+  });
+
+  const sseProvider = new HermesSseRunEventProvider({
+    httpBase: params.httpBase,
+    authToken: params.authToken,
+    clientId: params.clientId,
+    sessionKey,
+  });
+
+  const composed = params.fetchToolEventSnapshot
+    ? createRunStreamWithToolFallback({
+        primary: sseProvider,
+        toolEventFallback: new RunPreviewPollProvider({
+          fetchSnapshot: params.fetchToolEventSnapshot,
+        }),
+      })
+    : sseProvider;
+
+  let sawAssistantResponseEvent = false;
+
+  return await new Promise<StreamHermesChatRunResult>((resolve, reject) => {
+    let subscription: RunEventStreamSubscription | null = null;
+    let settled = false;
+    const settleResolve = (): void => {
+      if (settled) return;
+      settled = true;
+      resolve({ sawAssistantResponseEvent });
+    };
+    const settleReject = (error: unknown): void => {
+      if (settled) return;
+      settled = true;
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+
+    composed
+      .subscribe(
+        { runId, signal: params.signal },
+        {
+          onEvent: (event) => {
+            if (
+              event.event === RUN_STREAM_EVENT_NAMES.MESSAGE_DELTA ||
+              event.event === RUN_STREAM_EVENT_NAMES.RUN_COMPLETED ||
+              event.event === RUN_STREAM_EVENT_NAMES.RUN_FAILED ||
+              event.event === RUN_STREAM_EVENT_NAMES.RUN_CANCELLED
+            ) {
+              sawAssistantResponseEvent = true;
+            }
+            try {
+              params.onEvent(event);
+            } catch (handlerError) {
+              settleReject(handlerError);
+            }
+          },
+          onError: settleReject,
+          onComplete: settleResolve,
+        },
+      )
+      .then((sub) => {
+        subscription = sub;
+        if (settled) {
+          void Promise.resolve(sub.dispose());
+        }
+      })
+      .catch(settleReject);
+
+    if (params.signal) {
+      const onAbort = (): void => {
+        if (subscription) void Promise.resolve(subscription.dispose());
+        settleReject(new Error("aborted"));
+      };
+      if (params.signal.aborted) {
+        onAbort();
+      } else {
+        params.signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+  });
+}
+
+export const streamGatewayChatRun = streamHermesChatRun;

package/src/providers/hermes/client.ts

@@ -0,0 +1,21 @@
+import {
+  GatewayApiClient,
+  type GatewayCapabilities,
+  type GatewayRunStatus,
+} from "../../core/gateway/client/client.js";
+import type { HttpApiClientOptions } from "../../core/http/types.js";
+
+export type HermesCapabilities = GatewayCapabilities & {
+  object?: "hermes.api_server.capabilities" | string;
+  platform?: "hermes-agent" | string;
+};
+
+export type HermesRunStatus = GatewayRunStatus & {
+  object?: "hermes.run" | string;
+};
+
+export class HermesApiClient extends GatewayApiClient {
+  constructor(options: HttpApiClientOptions) {
+    super(options, "hermes-api-server");
+  }
+}