Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.0 KB
Raw Blame
/**
 * The thin-client error class and the tool-result envelope readers that a
 * local CLI command also names (instanceof checks, ignored-param warnings),
 * split out of mcp-client.ts so naming them never loads the MCP SDK types and
 * zod schema graph behind a remote call. mcp-client.ts re-exports all of it.
 */
import { canonicalCodeFor } from './error-catalogue.ts';
import { publicWriteReceipt, type WriteErrorCode, type WriteReceipt } from './persistence/types.ts';

/**
 * Stable union of failure reasons. The CLI dispatcher (cli.ts thin-client
 * routing branch, v0.31.1) uses an exhaustive TS switch over this union to
 * produce canned, actionable user messages — adding a new variant fails
 * compilation until every dispatcher knows what to render.
 *
 * v0.31.1 additions:
 *  - `kind` sub-tag on `network` errors distinguishes 'unreachable' /
 *    'timeout' / 'aborted' so callers can render the right hint.
 *  - `code` field on `tool_error` carries the MCP server's `error.code` (when
 *    present) so the dispatcher can map missing-scope etc. to pinpoint hints.
 */
export type RemoteMcpErrorReason =
  | 'config'
  | 'discovery'
  | 'auth'
  | 'auth_after_refresh'
  /** OAuth /token answered 429; `detail.retry_after_s` carries its Retry-After. */
  | 'rate_limited'
  /** OAuth /token failed after discovery succeeded (non-auth HTTP status or bad body). */
  | 'token'
  | 'network'
  | 'tool_error'
  | 'parse';

export interface RemoteMcpErrorDetail {
  status?: number;
  mcp_url?: string;
  /** v0.31.1: sub-tag for network errors (timeout vs aborted vs generic). */
  kind?: 'timeout' | 'aborted' | 'unreachable';
  /** v0.31.1: server-supplied error code on tool_error (e.g. 'missing_scope'). */
  code?: string;
  /** Seconds the server asked us to wait before minting again (rate_limited). */
  retry_after_s?: number;
  /** An accepted mutation's receipt survives the transport's tool-error wrapper. */
  write_request?: WriteReceipt;
  write_error?: WriteErrorCode;
  /** Retained even when no acknowledgment proves whether the write was accepted. */
  request_id?: string;
  submission_status?: 'unknown' | 'not_sent';
  message?: string;
  suggestion?: string;
  protocol_version?: 1;
  server_detail?: string;
  docs?: string;
  /** Agent contract v1: canonical registry code (`code`) when it differs from or adds to the wire `error` (kept in `code` above). */
  canonical_code?: string;
  reason?: string;
  why?: string;
  /** Rendered fix as the server sent it (`next` included). */
  fix?: Record<string, unknown>;
  /** Notices from the envelope's `notices` key (error results carry exactly one block). */
  notices?: Array<Record<string, unknown>>;
  contract_version?: 1;
}

export class RemoteMcpError extends Error {
  constructor(
    public readonly reason: RemoteMcpErrorReason,
    message: string,
    public readonly detail?: RemoteMcpErrorDetail,
  ) {
    super(message);
    this.name = 'RemoteMcpError';
  }

  /** Mutation error output shares the CLI/IPC envelope without inventing a receipt. */
  toJSON() {
    const detail = this.detail;
    const unknown = detail?.submission_status === 'unknown';
    const wire = detail?.code ?? 'unavailable';
    return {
      error: wire,
      code: detail?.canonical_code ?? canonicalCodeFor(wire),
      message: detail?.message ?? this.message,
      ...(detail?.request_id ? { request_id: detail.request_id } : {}),
      ...(detail?.submission_status ? { submission_status: detail.submission_status } : {}),
      ...(unknown ? { detail: 'delivery_unknown' } : detail?.server_detail ? { detail: detail.server_detail } : {}),
      suggestion: detail?.suggestion ?? (detail?.request_id
        ? `${unknown ? 'Submission state is unknown. ' : ''}Retry the same operation and arguments with request_id ${detail.request_id}; do not generate a replacement ID.`
        : 'Inspect the remote connection before retrying.'),
      ...(detail?.protocol_version === 1 ? { protocol_version: 1 } : {}),
      ...(detail?.docs ? { docs: detail.docs } : {}),
      ...(detail?.write_request ? { write_request: publicWriteReceipt(detail.write_request) } : {}),
      ...(detail?.write_error ? { write_error: detail.write_error } : {}),
      ...(detail?.reason ? { reason: detail.reason } : {}),
      ...(detail?.why ? { why: detail.why } : {}),
      ...(detail?.fix ? { fix: detail.fix } : {}),
      ...(detail?.notices?.length ? { notices: detail.notices } : {}),
      ...(detail?.contract_version === 1 ? { contract_version: 1 } : {}),
    };
  }
}

/**
 * T15/FOV-1: read the response-level `_meta` from a tool-call envelope
 * (see docs/protocol/MCP_META_CHANNELS.md). Old servers simply lack the
 * field — callers must treat undefined as "no meta", never as an error.
 */
export function extractResponseMeta(res: unknown): Record<string, unknown> | undefined {
  const meta = (res as { _meta?: unknown } | undefined)?._meta;
  if (meta && typeof meta === 'object' && !Array.isArray(meta)) {
    return meta as Record<string, unknown>;
  }
  return undefined;
}

/**
 * Params the server reported it ignored (WP3 warn mode): `_meta.warnings`
 * entries with code `unknown_param`, plus the model-visible warning blocks
 * after content[0] for transports that drop `_meta`. Empty for hosts that
 * predate unknown-parameter warnings, which cannot be detected.
 */
export function ignoredRemoteParams(res: unknown): string[] {
  const names = new Set<string>();
  const warnings = extractResponseMeta(res)?.warnings;
  if (Array.isArray(warnings)) {
    for (const w of warnings as Array<{ code?: unknown; param?: unknown }>) {
      if (w?.code === 'unknown_param' && typeof w.param === 'string') names.add(w.param);
    }
  }
  const content = (res as { content?: unknown[] } | undefined)?.content;
  for (const block of Array.isArray(content) ? content.slice(1) : []) {
    const text = (block as { text?: unknown })?.text;
    if (typeof text !== 'string') continue;
    for (const m of text.matchAll(/^(?:why: )?warning: unknown parameter "([^"]+)" ignored/gm)) names.add(m[1]);
  }
  return [...names];
}