get_trace_decisions

Instructions

Implementation Reference

• mcp-server/src/tools.ts:59-80 (handler)

  The handler for the 'get_trace_decisions' tool. Calls client.getTrace to fetch a trace, extracts decision events from the trace events using extractDecisionEvents, and returns the decisions as JSON.

  {
    name: "get_trace_decisions",
    description:
      "Extract normalized decision.* events from one trace. " +
      "Use this when a workflow includes proposal, override, approval, or binding steps.",
    inputSchema: {
      type: "object",
      properties: {
        trace_id: { type: "string", description: "The trace ID to inspect for decision events" },
      },
      required: ["trace_id"],
    },
    handler: async (client, args) => {
      const traceId = args.trace_id as string;
      const result = await client.getTrace(traceId);
      const events = Array.isArray(result.events) ? result.events : [];
      const decisions = extractDecisionEvents(events as Array<Record<string, unknown>>, {
        traceId,
      });
      return JSON.stringify({ trace_id: traceId, decisions }, null, 2);
    },
  },

• mcp-server/src/decisions.ts:68-82 (helper)

  Core helper that extracts normalized decision events from a trace event array. Maps events through extractDecisionPayload, filters out nulls, and optionally filters by workflowId, decisionId, or traceId.

  export function extractDecisionEvents(
    events: TraceEvent[],
    filters?: {
      workflowId?: string;
      decisionId?: string;
      traceId?: string;
    },
  ): DecisionPayload[] {
    return events
      .map((event) => extractDecisionPayload(event))
      .filter((payload): payload is DecisionPayload => payload !== null)
      .filter((payload) => !filters?.workflowId || payload.workflow_id === filters.workflowId)
      .filter((payload) => !filters?.decisionId || payload.decision_id === filters.decisionId)
      .filter((payload) => !filters?.traceId || payload.trace_id === filters.traceId);
  }

• mcp-server/src/decisions.ts:52-66 (helper)

  Helper that validates a trace event is a decision event via isDecisionEvent, then normalizes the payload into a DecisionPayload object with all standard decision fields.

  export function extractDecisionPayload(event: TraceEvent): DecisionPayload | null {
    if (!isDecisionEvent(event)) {
      return null;
    }
    const payload = isRecord(event.data) ? event.data : {};
    const normalized = {} as DecisionPayload;
  
    for (const field of DECISION_FIELDS) {
      normalized[field] = payload[field];
    }
  
    normalized.trace_id = normalized.trace_id ?? event.trace_id;
    normalized.event_type = normalized.event_type ?? event.name;
    return normalized;
  }

• mcp-server/src/decisions.ts:42-50 (helper)

  Helper that checks if a trace event is a decision event by verifying event kind is 'event' and the name or data.event_type is in the set of decision event types (proposed, edited, overridden, approved, bound).

  export function isDecisionEvent(event: TraceEvent): boolean {
    if (!isRecord(event) || event.kind !== "event") {
      return false;
    }
    if (typeof event.name === "string" && DECISION_EVENT_TYPES.has(event.name)) {
      return isRecord(event.data);
    }
    return isRecord(event.data) && typeof event.data.event_type === "string" && DECISION_EVENT_TYPES.has(event.data.event_type);
  }

• mcp-server/src/decisions.ts:9-26 (schema)

  Schema definition for decision fields and the DecisionPayload type. Defines the shape of normalized decision data extracted from trace events.

  const DECISION_FIELDS = [
    "decision_id",
    "workflow_id",
    "trace_id",
    "object_type",
    "object_id",
    "actor_type",
    "actor_id",
    "event_type",
    "proposal",
    "final",
    "diff",
    "reason",
    "comment",
    "timestamp",
    "binding_state",
    "outcome",
  ] as const;