/** Coarse status of a native agent as reported by the Herdr agent surface. */
export type NativeAgentStatus =
  | "idle"
  | "working"
  | "blocked"
  | "done"
  | "unknown";

/** A point-in-time observation from the native Herdr agent surface. */
export type NativeAgentObservation =
  | {
      kind: "present";
      agent?: string;
      agentStatus: NativeAgentStatus;
      observedAt?: number;
    }
  | { kind: "missing"; error?: string }
  | { kind: "unavailable"; error?: string };

/**
 * The narrow transport seam used by Completion supervision.
 *
 * Completion supervision deliberately knows neither panes nor Herdr. The
 * production adapter translates the native agent API into these observations;
 * tests can provide a deterministic implementation without starting Herdr.
 */
export interface NativeSupervisionAdapter {
  observe(signal: AbortSignal): Promise<NativeAgentObservation>;
}

export function createNativeSupervisionAdapter(
  observe: (signal: AbortSignal) => Promise<NativeAgentObservation>,
): NativeSupervisionAdapter {
  return {
    async observe(signal) {
      try {
        return await observe(signal);
      } catch (error) {
        // The adapter translates transport/query failures into the narrow
        // retryable observation understood by Completion supervision.
        return {
          kind: "unavailable",
          error: error instanceof Error ? error.message : String(error),
        };
      }
    },
  };
}

export function isNativeAgentObservation(value: unknown): value is NativeAgentObservation {
  if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
  const kind = (value as { kind?: unknown }).kind;
  if (kind === "missing" || kind === "unavailable") return true;
  if (kind !== "present") return false;

  const observation = value as { agentStatus?: unknown; observedAt?: unknown };
  const validStatus = observation.agentStatus === "idle" ||
    observation.agentStatus === "working" ||
    observation.agentStatus === "blocked" ||
    observation.agentStatus === "done" ||
    observation.agentStatus === "unknown";
  return validStatus && (observation.observedAt == null || Number.isFinite(observation.observedAt));
}