Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.5 KB
Raw Blame
import type { OperationMeta, ParamDef } from '../core/ops/contract.ts';

export interface McpToolDef {
  name: string;
  description: string;
  inputSchema: {
    type: 'object';
    properties: Record<string, unknown>;
    required: string[];
    /** WP3 (D14.1): emitted ONLY when buildToolDefs runs with strictParams. */
    additionalProperties?: false;
  };
  /**
   * MCP ToolAnnotations (SDK 1.29+): the op's own curated annotations, else
   * the conservative derivation in toolAnnotations(). Absent when neither
   * applies, so an op of unknown effect stays unannotated.
   */
  annotations?: {
    title?: string;
    readOnlyHint?: boolean;
    destructiveHint?: boolean;
    idempotentHint?: boolean;
  };
}

/**
 * Convert a single ParamDef to a JSON Schema fragment. Recursive on `items`
 * and object `properties` (closed, with member `required`).
 *
 * Single source of truth for ParamDef→JSON Schema mapping. Consumed by:
 * - buildToolDefs (stdio MCP server.ts via tool-defs.ts)
 * - serve-http.ts tools/list handler (HTTP MCP path)
 * - brain-allowlist.ts paramsToInputSchema (subagent tool registry)
 *
 * The three call sites previously each had their own inline destructure that
 * drifted from each other (live HTTP MCP path dropped `items` entirely in
 * v0.32 PR review). Centralizing here closes the bug class at the
 * architecture level instead of patching one site at a time.
 *
 * Key ordering (type, description, enum, default, items) is intentional —
 * matches the pre-v0.34 inline mappers so JSON.stringify output stays
 * byte-stable for the byte-equality regression test.
 */
export function paramDefToSchema(p: ParamDef): Record<string, unknown> {
  return {
    type: p.type === 'array' ? 'array' : p.type,
    ...(p.description ? { description: p.description } : {}),
    ...(p.enum ? { enum: p.enum } : {}),
    ...(p.default !== undefined ? { default: p.default } : {}),
    ...(p.items ? { items: paramDefToSchema(p.items) } : {}),
    ...(p.properties ? {
      properties: Object.fromEntries(Object.entries(p.properties).map(([k, v]) => [k, paramDefToSchema(v)])),
      required: Object.entries(p.properties).filter(([, v]) => v.required).map(([k]) => k),
      additionalProperties: false,
    } : {}),
  };
}

/**
 * WP3 (D14.1): when a strict schema closes the property set with
 * `additionalProperties: false`, the two dispatch-allowlisted passthrough
 * keys MUST be declared in `properties` — schema-validating clients
 * (Gemini strict, OpenAI structured outputs) would otherwise strip
 * `_meta.session_id` and `dry_run` from arguments before they ever reach
 * the server. Declared only when the op doesn't already declare them
 * (several ops carry a real `dry_run` param).
 */
function strictPassthroughProperties(op: OperationMeta): Record<string, unknown> {
  return {
    ...('_meta' in op.params ? {} : {
      _meta: {
        type: 'object',
        description: 'MCP client metadata passthrough (e.g. session id); not an operation parameter.',
      },
    }),
    ...('dry_run' in op.params ? {} : { dry_run: { type: 'boolean' } }),
    ...('room' in op.params ? {} : {
      room: {
        type: 'array',
        items: { type: 'string' },
        description: 'Set by the harness: who is in the shared chat this answer goes to. Hints only; never changes what is read.',
      },
    }),
  };
}

/**
 * #5037 / agent contract A2: annotation-driven hosts need to tell reads from
 * writes. An op's curated `annotations` win as written. Otherwise derive only
 * what the op's required metadata states (every op declares `mutating` and
 * `idempotent`; test/ops-mutation-tags.test.ts): `readOnlyHint: true` iff
 * `mutating === false`; `readOnlyHint: false` iff `mutating === true`, plus
 * `idempotentHint: true` when the write is also `idempotent`.
 * `destructiveHint` and `openWorldHint` keep the MCP defaults (no metadata
 * separates additive from destructive writes yet).
 */
export function toolAnnotations(op: OperationMeta): McpToolDef['annotations'] | undefined {
  if (op.annotations) return op.annotations;
  if (op.mutating === false) return { readOnlyHint: true };
  if (op.mutating === true) return op.idempotent === true ? { readOnlyHint: false, idempotentHint: true } : { readOnlyHint: false };
  return undefined;
}

/**
 * Build MCP tool definitions from operations.
 *
 * Default emission (no opts / strictParams false) is BYTE-IDENTICAL to the
 * pre-WP3 output — pinned by test/mcp-tool-defs.test.ts. With
 * `strictParams: true` (mcp.strict_params = 'reject'), each inputSchema
 * additionally declares the `_meta`/`dry_run` passthrough keys and closes
 * the schema with `additionalProperties: false`, keeping client-side
 * validation aligned with the server's reject posture.
 */
export function buildToolDefs(ops: OperationMeta[], opts?: { strictParams?: boolean }): McpToolDef[] {
  const strict = opts?.strictParams === true;
  return ops.map(op => {
    const annotations = toolAnnotations(op);
    return {
      name: op.name,
      description: op.description,
      inputSchema: {
        type: 'object' as const,
        properties: {
          ...Object.fromEntries(
            Object.entries(op.params).map(([k, v]) => [k, paramDefToSchema(v)]),
          ),
          ...(strict ? strictPassthroughProperties(op) : {}),
        },
        required: Object.entries(op.params)
          .filter(([, v]) => v.required)
          .map(([k]) => k),
        ...(strict ? { additionalProperties: false as const } : {}),
      },
      ...(annotations ? { annotations } : {}),
    };
  });
}